Skip to main content

Strapi CMS

This integration provides a full integration with Strapi CMS.

Requirements​

To use it, you must install it into the API Harmonization server by running:

npm install @o2s/integrations.strapi-cms --workspace=@o2s/api

This integration relies upon the following environmental variables:

nametypedescription
CMS_STRAPI_BASE_URLstringthe base URL pointing to the domain hosting Strapi CMS

Supported modules​

This integration handles following base modules from the framework:

  • cms

Dependencies​

This integration relies on the following base modules from the framework:

  • cache

GraphQL integration​

To connect with Strapi, the GraphQL API is used. For this purpose, a dedicated GraphqlService is used that relies on:

GraphQL operations​

The GraphqlService offers a few methods that can be used to retrieve data from the CMS:

  • getPage that retrieves the full definition of a single page (with SEO metadata, used layouts, and shared elements like header and footer) based on a given slug and locale,
  • getPages that retrieves all pages for a given locale,
  • getLoginPage to fetch the content for the login page,
  • getComponent that retrieves a single component with a given ID and locale.

Code generation​

You can generate code from GraphQL queries by running:

npm run generate
info

This command also requires that the CMS_STRAPI_BASE_URL environment variable to be set in order to retrieve the GraphQL schema from Strapi.

This will generate the ./generated/strapi.ts file, that is then used within the GraphqlService:

import { Sdk, getSdk } from '@/generated/strapi';
...
this.sdk = getSdk(this._client);

which then allows to call the methods generated from GrapQL queries using the sdk property:

public getComponent(params: GetComponentQueryVariables) {
    return this.sdk.getComponent(params);
}
info

Check the ./codegen.ts file for more details about used codegen config, including used TypeScript plugins.

Writing queries​

GraphQL queries should be placed in the ./src/cms/graphql folder, with additional divisions for:

  • ./queries for final queries that will be translated to TypeScript methods:

    ./src/cms/graphql/queries/getComponent.graphql
    query getComponent($id: ID!, $locale: I18NLocaleCode!) {
        component(documentId: $id, locale: $locale) {
            name
            content {
                __typename
                ... on ComponentComponentsFaq {
                    ...FaqComponent
                }
            }
        }
    }

  • ./fragments for reusable fragments, divided further into:

    • ./fragments/components that map to components within the frontend app:

      ./src/cms/graphql/fragments/components/Faq.graphql
      fragment FaqComponent on ComponentComponentsFaq {
          __typename
          id
          title
          subtitle
          items {
              title
              description
          }
      }

    • ./fragments/templates that map to templates within the frontend app:

      ./src/cms/graphql/fragments/templates/TwoColumnTemplate.graphql
      fragment TwoColumnTemplate on ComponentTemplatesTwoColumn {
          topSlot {
              ...Component
          }
          leftSlot {
              ...Component
          }
          rightSlot {
              ...Component
          }
          bottomSlot {
              ...Component
          }
      }

Strapi integration​

Resolving pages​

To resolve a single page to an entry within the CMS, the following process happens:

  1. All pages are fetched for a given locale
  2. From those pages, a single one is found with a slug that matches the requested slug; this match is found using Regex to allow pages with a slug like /tickets/{.+} to be defined in Strapi for dynamic pages with some dynamic IDs.

Content model​

Coming soon!

Importing sample content​

Coming soon!

Cache integration​

In order to allow further optimizations, the cache module is used for caching retrieved CMS entries (as long as caching is enabled globally).

Cached entries are stringified and saved using the {id}-{locale} key to make them fully unique within the caching service.