Netlify Docs
Ask Netlify

Contact

Netlify Create /Frameworks /

Use Netlify Create with Gatsby

Learn how to use Netlify Create with a Gatsby-based website.

For a tutorial see here. The completed tutorial is also available as an example repository.

# Configure Netlify Create for a Gatsby project

Here is an example stackbit.config.ts configuration file for working with Gatsby.

// stackbit.config.ts
import { defineStackbitConfig } from "@stackbit/types";

export default defineStackbitConfig({
  stackbitVersion: "~0.6.0",
  ssgName: "gatsby",
  ssgVersion: "5",
  nodeVersion: "18",
  contentSources: [
    // ...
  ]
});

// stackbit.config.ts
import { defineStackbitConfig } from "@stackbit/types";

export default defineStackbitConfig({
  stackbitVersion: "~0.6.0",
  ssgName: "gatsby",
  ssgVersion: "5",
  nodeVersion: "16",
  contentSources: [
    // ...
  ]
});

# Requirements

There are a few unique conditions when using a Gatsby project with Netlify Create:

  • Newer Gatsby versions have strict Node.js requirements, which must be passed on to Netlify Create.
  • Content reloading must be handled manually.
  • Running the development server requires specifying the host when using with Netlify Create.

See the sections below for more information.

# Specify the Node version

Newer versions of Gatsby have strict Node.js version requirements. For example, Gatsby 5.x requires Node 18+.

When working locally, ensure that you're running a compatible version of Node.js. In a cloud project, this can be configured using nodeVersion.

# Content reload

Gatsby caches content after fetching it from source plugins, and thus must be instructed to refresh when content is changed. This requires the following:

  1. Enable the refresh endpoint by setting the ENABLE_GATSBY_REFRESH_ENDPOINT environment variable to true. This can also be done inline when starting stackbit dev (see below).
  2. Leverage the stackbitObjectsChanged dispatched event to trigger a content refresh, being sure to override Netlify Create's default behavior by calling preventDefault() on the event object.

Here is a basic example that could be added to a page or app component. (Note that you may want to add environment checks in these listeners.)

import React, { useEffect } from "react";

export default function ComposablePageTemplate({ data }) {
  useEffect(() => {
    const handleContentChange = async event => {
      event.preventDefault();
      await fetch("/__refresh", { method: "POST" });
    };

    window.addEventListener("stackbitObjectsChanged", handleContentChange);

    return () => {
      window.removeEventListener("stackbitObjectsChanged", handleContentChange);
    };
  }, []);

  // ...
}

# Run Netlify Create locally

When using Netlify Create in local development with a Gatsby project, you must specify the host as 127.0.0.1 when starting your server.

npm run develop -- --host 127.0.0.1

Note

Notice the extra --, which passes on the host option to the gatsby command.

You may also wish to enable the refresh endpoint (noted above) inline with the command.

ENABLE_GATSBY_REFRESH_ENDPOINT=true npm run develop -- --host 127.0.0.1

# Example project

We have a fully-functioning, simple example app that uses Contentful as the content source. Use the create-stackbit-app command to clone the project to your machine.

npx create-stackbit-app@latest --example gatsby-contentful

Follow the README linked in the terminal output to get everything set up.

# Tutorial

If you'd like to follow a step-by-step tutorial to use Netlify Create with a Gatsby site, refer to the Gatsby + Contentful tutorial.