Add the Gatsby Cloud App to Contentful

Adding this app to the Contentful sidebar will make your preview edits update faster.

Prerequisites

The site must be set up with a Gatsby Preview instance. Please see “Getting Started with Gatsby Cloud and Contentful”.

Your site must also use either the latest Gatsby v3, v4, or later as well as the latest v5, v6, or later version of gatsby-source-contentful.

Installing App

To install the sidebar extension in your Contentful space follow the steps below.

1. Log in to your Contentful Dashboard

2. From the “Apps” Menu, select “Manage Apps”.

3. Find “Gatsby Cloud” in the list of apps and select.

4. A modal will open titled, “App details”, click install and you will be navigated to configure the app.

5. Authorize the Gatsby Cloud App to access your Contentful Space.

6. Fill in the inputs labeled “Preview Webhook” and "Content Sync" with the Preview Webhook URL and Content Sync URL of your Gatsby preview instance. You can find this in the Gatsby Cloud dashboard settings for your Preview instance.

7. (Optional) Fill in the input labeled “Authentication Token” with an authToken. This is necessary for Gatsby Preview instances that require the user to login before they can view the Preview. (Note that this doesn't yet work when using Content Sync)

8. Note that you can optionally use legacy Previews without Content Sync by omitting the "Content Sync" field and filling the "CMS Preview" field with the frontend URL of your Gatsby Cloud Preview site. This isn't recommended because legacy Previews will be removed in future versions. This should only be used as a temporary workaround if you're experiencing issues with Content Sync. See the bottom of this page for more info on Content Sync.

8. Click Install in the top right corner to finish configuring the app.

9. Navigate to a piece of content within Contentful. The sidebar will be installed and displayed to the right.

You can navigate to the preview instance by clicking “Open preview”. A webhook is sent to your Gatsby Cloud Preview site every time you open your preview. Content Sync will display a loading page while your preview content builds and then will automatically find and redirect you to the correct page when it's available to view.

Note: Legacy preview without Content Sync are debounced to send a webhook every 1 second as you make content changes.

What is Content Sync for Contentful?

Content Sync brings new super-powers to CMS Preview. When content editors click Open Preview, Content Sync jumps into action and routes content editors to the correct URL. It also helps them understand the status of preview, so they know when it's ready and if anything went wrong. It does this by displaying a loading state while the content preview builds. Once the build is complete the editor is redirected to the correct frontend page automatically.

Content Sync for Contentful will route you to the correct page even if you press "Open Preview" from within a nested node which has no associated top-level page.

If the build for the preview fails or if no page is created that contains the content being previewed, Content Sync UI will display an error message.

In the case that your content lives on multiple pages, for example a blog post page and a blog listing page, and you find you're being routed to the page you don't want to view your preview on, you can specify which content owns which page using the "ownerNodeId" setting in the "createPage" api. Set the "ownerNodeId" to the Gatsby node ID of the top-level Contentful node which is the main node you want to preview for the page.

You will not need to do this if you're building pages using the Filesystem Route API, or if your page context includes a matching "id" property.