RFC: Add Gatsby support to Slice Machine

[angeloashmore]

Overview

This RFC describes how Gatsby support could be added to Slice Machine.

Gatsby’s focus on static site generation and its internal GraphQL API presents challenges that do not exist in Next.js and Nuxt.

What and/or who is affected by this RFC?

• All Prismic users who use Gatsby to build websites
• The Slice Machine development team

Why is this being proposed?

Going forward, Slice Machine is the primary method to develop websites with Prismic. Currently, Slice Machine only officially supports Next.js and Nuxt. Gatsby has a large user base, but its users are unable to use Slice Machine (in an officially supported way).

Background Information

What is the current situation?

Today, Gatsby users can use Prismic in one of the two methods:

1. Use the Writing Room Custom Type editor

   This is the “classic” method of building Custom Types and Slices. Slices cannot be dynamically shared between Custom Types. Isolated development environments, such as developing Slice components, must be set up independently. In most cases, this involves using Storybook ad hoc.

2. Use Slice Machine in an unsupported fashion

   Slice Machine can be configured to use a universal “none” framework that disables component file generation and the Slice Simulator environment. This leaves Slice Machine as only a local Custom Type model builder and excludes its main benefits.

Slice Machine can also be “misconfigured” to use the Next.js integration (in a Gatsby site). The files that are produced are Next.js-specific, which means it lacks required code like GraphQL fragments for Slices.

Option #1 is the documented method of using Prismic with Gatsby. Option #2 is undocumented and not recommended.

What are the current problems?

As mentioned in the intro, Gatsby’s focus on static site generation and its internal GraphQL API presents challenges that do not exist in Next.js and Nuxt.

The extra GraphQL layer introduced by Gatsby creates a mis-match between Slice Machine’s generated mock files (which mimic Prismic’s Rest API V2) and Gatsby’s GraphQL API (which alters Prismic’s Rest API V2 data via gatsby-source-prismic).

Are there any related discussions from elsewhere?

A basic PR to add Gatsby support was opened back in July 2021 (see here). Since then, Slice Machine has been rearchitected, requiring changes to the PR.

Part of this PR involved updating gatsby-source-prismic and gatsby-plugin-prismic-previews to support Shared Slices. This work is complete and does not need further changes.

There is also interest from the community to provide Gatsby support, as seen in #277.

Proposal

Completing this effort ideally can be completed within two weeks of development time (documentation may take additional time).

This timeframe is given to help guide technical decisions. Supporting 90% of use cases in a short timeframe is favored over covering 100% of use cases in an extended timeframe.

Adding Gatsby support requires the following:

Slice Simulator

Define how Slice Simulator is set up in a Gatsby project.

• @prismicio/slice-simulator-react can be used, but the slices data must be transformed to mimic the GraphQL API (or sourced through the GraphQL API somehow). gatsby-source-prismic provides a “runtime” export that converts a Prismic Rest API V2 data payload to a simulated GraphQL API. It is used for gatsby-plugin-prismic-previews to provide client-side Preview support, but it can also be used in Slice Simulator for a similar purpose. It has limitations.
• Explore if there is a way to provide mock data to Gatsby through its data sourcing APIs. This is likely a very complex ask and may require a full mock API.

Setup steps

Write clear setup steps that appear in Slice Machine’s sidebar. See how this works for Next.

Gatsby-specific component template

Create an updated Slice component template file that uses the latest version of @prismicio/react and includes a basic GraphQL fragment. See how this works for Next.

Documentation

Updated documentation for using Slice Machine with Gatsby (and ideally becomes the primary method).

gatsby-source-prismic integration

Expose an easy to way provide Custom Type and Shared Slice models to gatsby-source-prismic. The plugin already accepts the JSON models as plugin options, but loading these JSON models is not currently automated in any way.

How it could be implemented

See the outdated PR for a general idea of an implementation strategy.

Also see this example project for a fully working example (using the not working, outdated PR).

The following portions of the example project are noteworthy:

• https://github.com/prismicio-community/gatsby-starter-slicemachine/blob/b7c65ae1d93efc36babf3d8f1972570853a1f203/gatsby-config.js#L3-L11 How loading Custom Type and Shared Slice models could work. This code could be abstracted and exported by gatsby-source-prismic (or built-in to the plugin and exposed as a plugin option).
• https://github.com/prismicio-community/gatsby-starter-slicemachine/blob/b7c65ae1d93efc36babf3d8f1972570853a1f203/src/pages/{PrismicPage.url}.js Using the generated fragments in a page would look something like this. While Slice Machine does not generate page files for the user, this code can be shared in documentation and example projects.

How to provide feedback

Anyone can provide feedback on everything mentioned in this RFC. If you have any thoughts or would like to see specific feature implemented, please comment on this issue.

If you are also interested in contributing code, please let me know!

Thanks! 😄

[hypervillain]

Closing for now after the new plugins architecture release