Use Visual Editor with Gatsby

Learn how to use Visual Editor with a Gatsby-based website.

Example Gatsby project with visual editing

See the example Gatsby project that is configured to work with Visual Editor and uses Contentful as a content source.

• Gatsby example project

Configure Visual Editor for a Gatsby project

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

Gatsby 5.x

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

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

Gatsby 3.x

// 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 Visual Editor:

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

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. If you’re not working locally, 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 Visual Editor’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 Visual Editor locally

When using Visual Editor 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