Skip to main content

Integration Guide: Contentful

Contentful is a headless content management system (CMS) that allows you to manage and deliver content across various platforms. Unlike a traditional CMS, it separates content from presentation, giving you the flexibility to build custom interfaces and deliver content to websites, apps, and more.

This guide provides detailed instructions on how to set up the official @archibald/contentful integration, which is designed to make it easier for teams to evaluate the product or switch an existing implementation to Contentful.

1. Add Credentials to Environment​

First, add your Contentful Space ID and API tokens to your environment configuration files. You can get these from your Contentful space settings.

// your-environment.json
"app": {
    "contentful": {
        "spaceId": "<YOUR_SPACE_ID>"
    }
},
"server": {
    "contentful": {
        "previewToken": "<YOUR_PREVIEW_TOKEN>",
        "contentToken": "<YOUR_CONTENT_TOKEN>"
    }
}

2. Configure the Server-Side (CMSModule)​

On the server, register the CMSModule with the ContentfulCMSProvider. This provider is included in the @archibald/contentful package.

// src/shop/server/module/server.tsx
import { CMSModule } from '@archibald/cms';
import { ContentfulCMSProvider } from '@archibald/contentful';
import { CoreServer } from '@archibald/server';

export class Server extends CoreServer {
    public async initModules() {
        const { contentful } = this.configService.get();
        await this.registerModules([
            new CMSModule({
                provider: new ContentfulCMSProvider({ config: contentful })
            }),
            // ... other modules
        ]);
    }
}

ContentfulCMSProvider Deep Dive​

The ContentfulCMSProvider is designed to streamline a migration from a commerce-based CMS to Contentful. It contains transformation logic to make the Contentful data structure compatible with Archibald's standard CMS components.

  • getPage(): This is the primary method. It fetches entries with the content type pageTemplate where the slug field matches the request. It then transforms the response, restructuring slot fields and resolving nested components.
  • getCMSEntries(): This method allows you to get raw CMS entries directly from Contentful, skipping the transformation logic. This is useful if you need the original, unmodified Contentful response for a custom component.

If you are starting a new project (greenfield), it may be advisable to create a simpler, new provider, as you might not need the transformation logic built into this provider.

3. Configure the Client-Side (CMSClient)​

On the client, configure the CMSClient to use the ContentfulCMSAdapter. The previewOptions are particularly important for enabling Contentful's Live Preview.

// src/shop/client/api/creators/cms.ts
import { CMSClient } from '@archibald/cms';
import { ContentfulCMSAdapter } from '@archibald/contentful';
import { api } from 'shop/client/api';
import Config from '@archibald/config';

export default new CMSClient({
    adapter: ContentfulCMSAdapter,
    api,
    previewOptions: { // See https://github.com/contentful/live-preview for more info
        targetOrigin: '*', // Adjust for production environments
        space: Config.app.contentful.spaceId,
        environment: 'master', // Or your specific Contentful environment
        locale: 'en-US', // Your default locale
        enableInspectorMode: true,
        enableLiveUpdates: true,
        debugMode: false,
        fallbackContentRoute: 'cp', // Your content route (e.g., 'cp')
    }
});

4. Import the Default Content Model (Optional)​

To get started quickly, you can import a default content model that aligns with the Archibald Shop project. This process uses the contentful-cli.

Install the CLI​

npm install -g contentful-cli

Login to Contentful​

Follow the official CLI authentication docs to log in to your Contentful space with a management token.

Import the Model​

You will need to get the space-id and management-token for a reference space from the Archibald team. Then you can run an export from that space and import it into your own.

# First, export the content model from the reference space
contentful space export \
  --space-id <REFERENCE_SPACE_ID> \
  --management-token <REFERENCE_MANAGEMENT_TOKEN> \
  --skip-content --skip-roles --skip-tags --skip-webhooks \
  --download-assets

# Then, import it into your own space
contentful space import \
  --space-id <YOUR_SPACE_ID> \
  --content-file <PATH_TO_EXPORTED_FILE.json>

5. Generate TypeScript Types (Optional)​

For type safety, you can generate TypeScript types from your Contentful schema using a tool like cf-content-types-generator.

pnpx cf-content-types-generator -s <YOUR_SPACE_ID> -t <YOUR_MANAGEMENT_TOKEN> -o <OUTPUT_PATH>

Remember to re-run this command whenever you update your content model in Contentful.