Netlify Docs
Ask Netlify

Contact

Visual editing /Visual Editor /Frameworks /

Use Visual Editor with Gatsby

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

# Configure Visual Editor 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 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