Working with `@archibald/contentful`

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

With this integration we aim to make it easier for teams to evaluate the product in an existing setup and have a simplified process for switching your implementation to contentful. In a green field approach the content model can serve as a starting point.

By using the @archibald/cms module as a common baseline, this integration can replace the @archibald/commerce cms integration.

Setup the contentful integration

Add credentials

In your environment config you will need to add the contentful credentials.

Please refer to the official documentation to create the needed tokens and setup your content preview (e.g. https://www.contentful.com/developers/docs/tutorials/preview/content-preview/).

app: {
    contentful: {
        spaceId: '<SPACE_ID>'
    }
},
server: {
    contentful: {
        previewToken: '<PREVIEW_TOKEN>',
        contentToken: '<CONTENT_TOKEN>'
    }
}

Initialize CMS client and server module

To get started you have to select the ContentfulCMSAdapter when creating your cms client. For more information check the documentation for the CMS module '@archibald/cms'.

export default new CMSClient({
    adapter: ContentfulCMSAdapter,
    api,
    previewOptions: { // see https://github.com/contentful/live-preview for more info on ContentfulLivePreview options
        targetOrigin: string;
        space: string; // can be read from Config.app.contentful.spaceId
        environment: string;
        locale: string;
        enableInspectorMode?: boolean;
        enableLiveUpdates?: boolean;
        debugMode?: boolean;
        fallbackContentRoute?: string; // define your content route (e.g. 'cp'), which is used in case no redirectUrl is supplied
    }
});

In your server.tsx the CMSModule should be initialized with the ContentfulCMSProvider

    new CMSModule({ provider: new ContentfulCMSProvider({ config: contentful }) })

Import default content model

You can make use of the default content model for Contentful which was setup with the Archibald Shop project. It fits into all the types used in the Provider and sets you up with a starting point. If you need help with accessing the instance, please reach out to the archibald team in slack.

For this we can use the contentful-cli. You can find the full official documentation here: https://www.contentful.com/developers/docs/tutorials/cli/import-and-export/

Install dependency

npm install -g contentful-cli
# Or
yarn global add contentful-cli

Follow the official documentation to setup a management token and login to your contentful space: https://www.contentful.com/developers/docs/tutorials/cli/authentication/

Export Content Model

contentful space export \
  --space-id 948ykwkj6i6u \
  --skip-content \
  --skip-roles \
  --skip-tags \
  --skip-webhooks

(Optional) Generate types

You can generate typescript types from your Contentful Schema using a package like cf-content-types-generator. You'll need your management token and space key again and then you can run

pnpxcf-content-types-generator -s=<SPACE_KEY> -t=<MANAGEMENT_TOKEN> -o=<OUTPUT_PATH>

Be aware that you will have to update your types if you make changes to the content model.

Setup the contentful integration​

Add credentials​

Initialize CMS client and server module​

Import default content model​

Install dependency​

Login​

Export Content Model​

(Optional) Generate types​