Accurate as of November 17, 2021

gatsby-source-prismic and its companion preview plugin, gatsby-plugin-prismic-previews, provide internal support for Shared Slices built with Slice Machine. Using Slice Machine with Gatsby is not official supported today, however. You can use Slice Machine with Gatsby in an experimental "framework-less" mode.

The following Slice Machine features are not supported:

The following guide assumes you have an existing Gatsby project. One can be created using Gatsby's init command: npm init gatsby

⚠️ Disclaimer: This guide is not supported by Prismic. APIs may change without notice. When full Gatsby support is added to Slice Machine, it may require changes to your code. Expect times where you may need to debug or restructure your app to work around Slice Machine's generated files. If this is an issue for you, we recommend not using Slice Machine with Gatsby.

Setup

  1. Install Slice Machine:

    npm install --save-dev slice-machine-ui
    
  2. Add a slicemachine script to package.json:

    // package.json
    
    {
      "scripts": {
        "slicemachine": "start-slicemachine"
      }
    }
    
  3. Create a sm.json file with the following contents (be sure to update your API endpoint with your Prismic repository name):

    {
      "_latest": "0.1.0",
      "apiEndpoint": "<https://your-repo-name.cdn.prismic.io/api/v2>",
      "libraries": ["@/src/slices"],
      "framework": "none"
    }
    

    "framework": "none" is the important part here. It lets Slice Machine run in a framework-agnostic mode. This tells Slice Machine to only be used to build and manage Prismic models. Slice Machine will not generate components or Storybook stories in this mode.

  4. Install gatsby-source-prismic and its peer dependencies:

    npm install gatsby-source-prismic gatsby-plugin-image
    
  5. Create a gatsby-config.js file with the following contents. If you have an existing gatsby-config.js, you can merge the contents.

    require("dotenv").config();
    
    const customTypeModels = require("fs")
      .readdirSync("./customtypes", { withFileTypes: true })
      .filter((entry) => entry.isDirectory())
      .map((dir) => require(`./customtypes/${dir.name}/index.json`));
    
    const sharedSliceModels = require("fs")
      .readdirSync("./src/slices", { withFileTypes: true })
      .filter((entry) => entry.isDirectory())
      .map((dir) => require(`./src/slices/${dir.name}/model.json`));
    
    module.exports = {
      plugins: [
        "gatsby-plugin-image",
        {
          resolve: "gatsby-source-prismic",
          options: {
            repositoryName: process.env.GATSBY_PRISMIC_REPOSITORY_NAME,
            accessToken: process.env.PRISMIC_ACCESS_TOKEN,
            customTypesApiToken: process.env.PRISMIC_CUSTOM_TYPES_API_TOKEN,
            customTypeModels,
            sharedSliceModels,
          },
        },
      ],
    };
    

    It is important to include the customTypeModels and sharedSliceModels options. This will load the models generated by Slice Machine into Gatsby.

    The customTypesApiToken option will automatically fetch any models not saved locally. Providing this token is optional if all of your models are managed by Slice Machine locally.

After these steps, Slice Machine is configured to create and manage Prismic models. Gatsby is also configured to load these models.