CMS for Gatsby: content, builds and previews
Connect a CMS to a Gatsby retail site through the documented content, build and preview path, then verify the approved version customers receive.
- Published
- Last updated
A CMS for Gatsby supplies editorial content that Gatsby reads to build your website. Connect the published content source to the production build, keep draft previews separate and verify the corrected page after deployment. Contentful is one documented connection, with separate delivery and preview access for the two jobs.
Identify the content and build arrangement
Record the Gatsby version, CMS source integration and hosting service your site actually uses. Gatsby’s documentation identifies Gatsby as a website framework. Its name alone does not tell you where a site builds or how a saved article reaches customers.
Check the installed Gatsby and source-plugin versions against their release requirements before changing the integration. Identify the repository, build command and output directory in the host’s configuration. For a static site, the production command is normally gatsby build, with the generated site in public.
Keep former hosting instructions separate from framework instructions. Contentful marks its Gatsby Cloud app as deprecated. A proposal that promises Gatsby Cloud previews needs a replacement arrangement tied to the hosting account you will operate.
For sites hosted on Netlify, its Gatsby setup guide describes framework-specific deployment requirements. Apply the section for your Gatsby version and rendering mode. Another host needs its own build and delivery configuration.
Define the editorial record
Use the CMS for authored buying guides, category explanations and store policies. Keep orders, checkout prices and stock with their transactional source. A guide can reference a catalogue identifier without storing another manually updated stock count.
For a hypothetical furniture guide, define a title, slug, body, hero image and catalogue references. Add an internal revision field so editors can trace a correction through the build. Write down which fields the page template reads and what it does when a linked product disappears.
If you are still choosing the editing system, compare headless CMS platforms against your approval and content-recovery needs before configuring Gatsby’s source integration.
Read and preview the content
Use a published content connection for production and a separate draft connection for editorial previews. The following setup uses the official gatsby-source-contentful plugin and a hypothetical guide record.
- Configure
gatsby-source-contentfulingatsby-config.jswith the intendedspaceIdandenvironment. SupplyaccessTokenthrough a build environment variable. For production, use a Content Delivery API token and the default delivery host,cdn.contentful.com. - Publish a guide with the required fields populated. Query its generated Contentful node in Gatsby’s local GraphQL explorer, selecting its slug, body and image reference. The expected record is the approved guide from the configured environment.
- Map the record to its page template and build the site. Open the generated guide and check its heading, image and catalogue links. Record the internal revision with the build evidence.
The plugin documentation warns that fields with no populated instances can be absent from its generated schema. Populate the fields your template requires and define the schema deliberately where stable queries need it. A missing optional image must have an agreed rendering outcome.
Keep draft access out of production
Contentful’s Content Preview API documentation distinguishes the published-content API from its read-only draft API. Preview uses a separate token and host. The preview token allows access to unpublished content, so restrict it to the preview build or server and keep it out of browser bundles.
Give the production token access only to the environments the integration requires. The source plugin documents an access requirement for both the selected environment and master. Keep management credentials out of the delivery build.
Create a separate preview deployment protected by your host’s access controls. Configure its Contentful preview token with host: preview.contentful.com. Contentful’s preview setup guide describes how to assign preview URLs to content types.
The plugin warns that preview synchronisation is unsupported by Contentful and can produce broken content over time. Use a clean preview build when validating a correction. Do not assume the old Gatsby Cloud preview app supplies this workflow.
Make a draft-only wording change in the example guide. An authorised reviewer must see it in the preview. An unauthenticated customer must see the previous approved version on the public route and must be unable to open the protected preview. Complete both checks before letting editors rely on the preview link.
Verify the customer-facing correction
Trace a policy correction from the published CMS record to the deployed guide, with an identifiable revision at each stage. A saved record and a successful webhook request are intermediate events. The acceptance result is the corrected content at the customer’s address.
For example, use a hypothetical bulky-item delivery correction referenced by the furniture guide. Preserve the prior approved record, then run this sequence:
- Edit the policy and have the authorised publisher approve it. Record the policy identifier and revised internal version.
- Trigger the production build through the configured publication event. For Netlify, a CMS webhook can send a POST request to a build hook associated with the intended branch. Keep the hook address private and confirm builds are active.
- Follow that event to the completed build and deployment. Check that the build reads the intended published environment with production credentials.
- Open the public policy and guide without editor access. Confirm the corrected wording, working product references and images. Match the served content to the revision recorded for the deployment.
If customer answers use an export or index of these pages, trace that update separately. Confirm that the answer source contains the same approved policy correction. A corrected browser page does not itself prove that another content consumer has refreshed.
Locate a failed correction
Work from the content source towards the customer page. Each check below has an expected result that helps locate the failure.
| Symptom | Check | Expected result and repair |
|---|---|---|
| Guide missing from the source query | Inspect publication state, environment, locale and query filter | The approved guide appears in the intended query. Correct the source or filter before rebuilding. |
| Build fails after an edit | Read the first source or query error in the build log | Required fields and references satisfy the template. Repair the content or schema, then build again. |
| Text changes but the image breaks | Inspect the published asset and the generated image address | The asset loads from the deployed page. Publish the referenced asset or repair its query and rebuild. |
| Deployment succeeds but old wording remains | Compare the completed deployment with the production domain and a fresh browser request | The domain serves the intended deployment. Correct its deployment selection or stale delivery cache after confirming the build contains the correction. |
Recheck the same public route after the repair. If the deployment contains incorrect policy wording, restore the previous approved version through the agreed recovery process while the editor corrects the source.
Assign the maintenance work
Name an owner for each part of the CMS-to-Gatsby path so a content change cannot leave an unanswered build failure. The retail editor owns policy accuracy and approval. The development team owns the source plugin, template queries and field definitions.
Give the hosting owner responsibility for build credentials, publication hooks and deployment alerts. A failed build notification must reach someone who can diagnose it, with an agreed escalation when that person is unavailable.
Keep recovery instructions for content and deployments separately. Restoring an earlier deployment changes the served site, while a later build can read the still-incorrect CMS record again. The recovery owner must know which source revision belongs with the restored deployment.
Before upgrading Gatsby or changing the CMS model, repeat the guide publication and draft-isolation checks on a separate test environment. Accept the change when the protected preview shows the draft, the public route shows the approved correction and a failed build reaches its named owner.
Give your store its own shopping agent
Customers ask in their own words. Your agent finds, compares and checks out from your catalogue, right on your site.