npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@eknowles/gatsby-source-prismic-graphql

v4.0.1

Published

Source data from Prismic with GraphQL

Downloads

13

Readme

gatsby-source-prismic-graphql

Source data from Prismic with GraphQL

Differences from gatsby-source-prismic

This plugin will require graphql enabled in your Prismic instance.

The feature is currently in alpha and not recommended in production. However that being said, by using Gatsby you have the garantee of production builds to never break as they are statically compiled.

Installing

Install module

npm install --save gatsby-source-prismic-graphql

Add plugin to gatsby-config.js:

{
  resolve: 'gatsby-source-prismic-graphql',
  options: {
    repositoryName: 'gatsby-source-prismic-test-site', // (required)
    accessToken: '...', // (optional)
    prismicRef: '...', // (optional, if not used then defaults to master ref. This option is useful for a/b experiments)
    path: '/preview', // (optional, default: /preview)
    previews: true, // (optional, default: false)
    pages: [{ // (optional)
      type: 'Article',         // TypeName from prismic
      match: '/article/:uid',  // Pages will be generated under this pattern (optional)
      path: '/article',        // Placeholder page for unpublished documents
      component: require.resolve('./src/templates/article.js'),
    }],
    sharpKeys: [
      /image|photo|picture/, // (default)
      'profilepic',
    ],
  }
}

Edit your gatsby-browser.js:

const { registerLinkResolver } = require('gatsby-source-prismic-graphql');
const { linkResolver } = require('./src/utils/linkResolver');

registerLinkResolver(linkResolver);

Usage

Fetch data from Prismic

It is very easy to fetch data from prismic.

import React from 'react';
import { RichText } from 'prismic-reactjs';

export const query = graphql`
  {
    prismic {
      page(uid:"homepage", lang:"en-us") {
        title
        description
      }
    }
  }
`

export default function Page({ data }) => <>
  <h1>{RichText.render(data.prismic.title)}</h1>
  <h2>{RichText.render(data.prismic.description)}</h1>
</>

Prismic Previews

Previews are enabled by default.

Read how to enable previews in your prismic instance.

Generated pages

You can generate pages automatically by providing mapping configuration under the pages option.

If you have two blog posts like foo, bar, it will generate the following URLs:

  • /blogpost/foo
  • /blogpost/bar

If you create a new unpublished blogpost, baz it will be accessible for preview under:

  • /blogpost?uid=baz

See the example

{
  pages: [{
    type: 'Article',
    match: '/blogpost/:uid',
    path: '/blogpost',
    component: require.resolve('./src/templates/article.js'),
  }],
}

StaticQuery

You can use static queries like normal, but if you would like to preview them, use the withPreview function.

See the example

import { StaticQuery, graphql } from 'gatsby';
import { withPreview } from 'gatsby-source-prismic-graphql';

const articlesQuery = graphql`
  query {
    prismic {
      ...
    }
  }
`;

export const Articles = () => (
  <StaticQuery
    query={articlesQuery}
    render={withPreview(data => { ... }, articlesQuery)}
  />
);

useStaticQuery

No support yet.

Fragments

Fragments are supported for both page queries and static queries.

See the example

Page components:

import { graphql } from 'gatsby';

const fragmentX = graphql` fragment X on Y { ... } `;

export const query = graphql`
  query {
    ...X
  }
`;

const MyPage = (data) => { ... };
MyPage.fragments = [fragmentX];

export default MyPage;

StaticQuery:

import { StaticQuery, graphql } from 'gatsby';
import { withPreview } from 'gatsby-source-prismic-graphql';

const fragmentX = graphql` fragment X on Y { ... } `;

export const query = graphql`
  query {
    ...X
  }
`;

export default () => (
  <StaticQuery
    query={query}
    render={withPreview(data => { ... }, query, [fragmentX])}
  />
);

Pagination and other dynamic fetching

You can use this plugin to dynamically fetch different component for your component. This is great for cases like pagination. See the following example:

See the example

import React from 'react';
import { graphql } from 'gatsby';

export const query = graphql`
  query Example($limit: Int) {
    prismic {
      allArticles(first: $limit) {
        edges {
          node {
            title
          }
        }
      }
    }
  }
`;

export default function Example({ data, prismic }) {
  const handleClick = () =>
    prismic.load({
      variables: { limit: 100 },
      query, // (optional)
      fragments: [], // (optional)
    });

  return (
    // ... data
    <button onClick={handleClick}>load more</button>
  );
}

Working with gatsby-image

Latest version of the plugin supports gatsby-image by adding a new property to graphql types that contain fields that match the sharpKeys array (this defaults to /image|photo|picture/) with the Sharp suffix.

Note: When querying, make sure to also query the source field, eg.

query {
  prismic {
    Article(id: "123") {
      title
      articlePhoto
      articlePhotoSharp {
        childImageSharp {
          fluid(maxWidth: 400, maxHeight: 250) {
            ...GatsbyImageSharpFluid
          }
        }
      }
    }
  }
}

You can also get access to specific crop sizes from Prismic by passing the crop argument:

query {
  prismic {
    Author(id: "123") {
      name
      profile_picture
      profile_pictureSharp(crop: "face") {
        childImageSharp {
          fluid(maxWidth: 500, maxHeight: 500) {
            ...GatsbyImageSharpFluid
          }
        }
      }
    }
  }
}

NOTE Does not transform images in preview mode, so make sure to fallback to the default image when the sharp image is null.

import Img from 'gatsby-image';
import get from 'lodash/get';

// ...

const sharpImage = get(data, 'prismic.Author.profile_pictureSharp.childImageSharp.fluid');
return sharpImage ? (
  <Img fluid={sharpImage} />
) : (
  <img src={get(data, 'prismic.Author.profile_picture.url')} />
);

Later we may add a Image component that does this for you, and leverages the new Prismic Image API as fallback for preview modes.

Prismic.io content a/b experiments integration

You can use this plugin in combination with Prismic's built-in experiments functionality, and a hosting service like Netlify, to run content a/b tests.

Experiments in Prismic are basically branches of the core content, split into 'refs' similar to git branches. So if you want to get content from a certain experiment variation, you can pass the corresponding ref through to Prismic in your request, and it will return content based on that ref's variation.

A/B experiments are tricky to implement in a static website though; a/b testing needs a way to dynamically serve up the different variations to different website visitors. This is at odds with the idea of a static, non-dynamic website.

Fortunately, static hosting providers like Netlify allow you to run a/b tests at a routing level. This makes it possible for us to build multiple versions of our project using different source data, and then within Netlify split traffic to our different static variations.

Therefore, we can use a/b experiments from Prismic in the following way:

  1. Setup an experiment in Prismic.

  2. Create a new git branch of your project which will be used to get content. You will need to create a separate git branch for each variation.

  3. In that git branch, edit/add the optional 'prismicRef' parameter (documented above). The value of this should be the ref of the variation this git branch is for.

  4. Push the newly created branch to your git repo.

  5. Now go to your static hosting provider (we'll use Netlify in this example), and setup split testing based on your git branches/Prismic variations.

  6. Now your static website will show different experimental variations of the content to different users! At this point the process is manual and non-ideal, but hopefully we'll be able to automate it more in the future.

How this plugin works

  1. The plugin creates a new page at /preview (by default, you can change this), that will be your preview URL you setup in the Prismic admin interface.

    It will automatically set cookies based on the query parameters and attempt to find the correct page to redirect to with your linkResolver.

  2. It uses a different babel-plugin-remove-graphql-queries on the client.

    The modified plugin emits your graphql queries as string so they can be read and re-used on the client side by the plugin.

  3. Once redirected to a page with the content, everything will load normally.

    In the background, the plugin takes your original gatsby graphql query, extracts the prismic subquery and uses it to make a graphql request to Prismic with a preview reference.

    Once data is received, it will update the data prop with merged data from Prismic preview and re-render the component.

Development

git clone [email protected]:birkir/gatsby-source-prismic-graphql.git
cd gatsby-source-prismic-graphql
yarn install
yarn setup
yarn start

# select example to work with
cd examples/default
yarn start

Issues and Troubleshooting

This plugin does not have gatsby-plugin-sharp support.

Please raise an issue on GitHub if you have any problems.

My page graphql query does not hot-reload for previews

This is a Gatsby limitation. You can bypass this limitation by adding the following:

export const query = graphql` ... `;
const MyPage = () => { ... };

MyPage.query = query; // <-- set the query manually to allow hot-reload.