SHOPin Logo
Skip to main documentation content

Set up Contentful

The SHOPin storefront accelerator uses Contentful for CMS-backed pages (by slug), layout (header/footer), and teaser sections when the BFF runs commercetools-set with integrations/contentful-api enabled. Runtime reads use the Content Delivery API (and optionally Preview). Migrations in integrations/contentful-migration use the Management API to install content types aligned with SHOPin storefront accelerator teasers and related models.

For the full variable list and inline comments, see How to setup SHOPin — Environment variables and .env.example. Repository clone, creating .env, installing dependencies, and running dev servers are covered in How to setup SHOPin — this page covers Contentful-only steps.

Prerequisites

  • A Contentful account and a space (often environment master, or another you configure).
  • For the default stack: commercetools-set with Commercetools configured (Set up Commercetools), since Contentful page/layout services are used alongside that data source in the stock BFF.

1. API keys and tokens

Delivery and Preview (runtime)

  1. In Contentful, open your space.
  2. Go to Settings → API keys and create or select a key for Content delivery / preview.
  3. Add values to the repository root .env using the CONTENTFUL_* names in .env.example: Content Delivery token → CONTENTFUL_ACCESS_TOKEN; optional Preview token → CONTENTFUL_PREVIEW_ACCESS_TOKEN; space and environment → CONTENTFUL_SPACE, CONTENTFUL_ENVIRONMENT (for example master). Space ID: Settings → General settings.

Management API (migrations)

Migrations use a personal access token (Management API), not the Delivery/Preview keys.

  1. Open your profile menu → Personal access tokens.
  2. Generate a token and store it once in .env as CONTENTFUL_MANAGEMENT_ACCESS_TOKEN.

See Environment variables for how that token differs from Delivery/Preview tokens.

2. Apply content model (migrations)

Follow integrations/contentful-migration/README.md in the SHOPin storefront accelerator repository for commands, subcommands, demo content, and locale notes.

3. Draft mode (Next.js)

If the presentation app uses draft/preview entry points, set NEXT_DRAFT_MODE_SECRET in .env to a strong random value (see comments in .env.example). This is separate from Contentful’s Preview API access token.

4. BFF wiring (Contentful vs mock layout)

In the default accelerator, ContentfulApiModule is imported in the BFF data-source.module.ts. With commercetools-set, page and layout services use Contentful when that module is present and Delivery/Preview and space env vars are set.

To use mock page and layout for commercetools-set instead of Contentful, remove ContentfulApiModule from that module as described in the BFF README (mock content for commercetools-set).

5. Verify

Run npm run dev and check that CMS-driven pages and layout look right in the storefront. If not, use Troubleshooting below.

Troubleshooting

IssueWhat to check
401 / Unauthorized from ContentfulCONTENTFUL_ACCESS_TOKEN, CONTENTFUL_SPACE, CONTENTFUL_ENVIRONMENT; API key not revoked.
Preview or draft failsCONTENTFUL_PREVIEW_ACCESS_TOKEN, NEXT_DRAFT_MODE_SECRET, and preview-enabled content.
Migrations failCONTENTFUL_MANAGEMENT_ACCESS_TOKEN, space/environment vars; contentful-migration README.
Layout or pages missingContentfulApiModule still imported; DATA_SOURCE; content published in the configured environment.

Related

Back to Integration setup