Installation

Here are the steps to install and configure the Front-Commerce Prismic module. This guide assumes that you are working in a Front-Commerce skeleton environment and you have access to a Prismic repository.

Install the module with npm:

First, make sure you have access to the Front-Commerce Prismic module repository. Then you can run the following command:

npm install git+ssh://git@gitlab.com/front-commerce/front-commerce-prismic.git

Configure the environment for Prismic

In the .env file, you have to define the following environment variables:

FRONT_COMMERCE_PRISMIC_REPOSITORY_NAME=your-repository
FRONT_COMMERCE_PRISMIC_ACCESS_TOKEN=the-very-long-access-token-from-prismic
FRONT_COMMERCE_PRISMIC_WEBHOOK_SECRET=a-secret-defined-in-webhook-configuration
#FRONT_COMMERCE_PRISMIC_API_CACHE_TTL_IN_SECONDS=60

• FRONT_COMMERCE_PRISMIC_REPOSITORY_NAME is the Prismic repository name
• FRONT_COMMERCE_PRISMIC_ACCESS_TOKEN is the access token for the repository, go to Settings > API & Security and create an application and copy the Permanent access token generated for this application
• FRONT_COMMERCE_PRISMIC_WEBHOOK_SECRET is a secret key used to clear caches in Front-Commerce and to secure Integration Fields API endpoints. To define it, go to Settings > Webhook and create a webhook pointing to your Front-Commerce URL https://my-shop.example.com/prismic/webhook. In the webhook form, you can configure a Secret. This is the one you should use in this environment variable.
• FRONT_COMMERCE_PRISMIC_API_CACHE_TTL_IN_SECONDS is an optional configuration that allows to customize the TTL of Prismic API cache. Shortening it allows to prioritize data freshness in environments not targeted by a Prismic webhook over performance. It defaults to 23h in production environments and 1min in staging and dev environments.

In case of trouble, front-commerce:prismic (or front-commerce:prismic* to include more specific namespaces) can be added to the DEBUG environment variable value, this value turns the debug on for Prismic module and make it verbose.

Simulate the webhook in a development environment

Configuring a webhook is required so that Front-Commerce fetches the last version of the Prismic content. In a development environment, you might skip this step. Data will get refreshed regularly depending on your FRONT_COMMERCE_PRISMIC_API_CACHE_TTL_IN_SECONDS configuration. In some situations, you may want to simulate Prismic webhooks to ensure your data uses the latest Prismic version without restarting the application.

You can simulate the webhook by issuing a POST request to http://dev-fc-url/prismic/webhook with the HTTP client of your choice. The body of this request must be a JSON object similar to {"secret": "the value of FRONT_COMMERCE_PRISMIC_WEBHOOK_SECRET", "type": "api-update", "masterRef": true}.

For instance, you can use the following curl command:

curl --request POST 'http://dev-fc-url/prismic/webhook' \
--header 'Content-Type: application/json' \
--data-raw '{
    "secret": "the value of FRONT_COMMERCE_PRISMIC_WEBHOOK_SECRET", "type": "api-update", "masterRef": true
}'

From the root of your Front-Commerce project, you can use the following oneliner, it will build and execute the command from the .env file content:

source .env ; PAYLOAD=`printf '{"secret": "%s", "type": "api-update", "masterRef": true}' $FRONT_COMMERCE_PRISMIC_WEBHOOK_SECRET` ; curl -H "Content-Type: application/json" -d "$PAYLOAD" $FRONT_COMMERCE_URL/prismic/webhook

Configure Front-Commerce to use the Prismic module

For that, you have to apply some changes to your .front-commerce.js.

module.exports = {
  ...
  modules: [
    "./node_modules/front-commerce/modules/datasource-elasticsearch",
    "./node_modules/front-commerce/theme-chocolatine",
+   "./node_modules/front-commerce-prismic/prismic",
    "./src",
  ],
  serverModules: [
    { name: "FrontCommerce", path: "server/modules/front-commerce" },
    {
      name: "Magento2Elasticsearch",
      path: "datasource-elasticsearch/server/modules/magento2-elasticsearch",
    },
    { name: "Magento2", path: "server/modules/magento2" },
+   { name: "Prismic", path: "prismic/server/modules/prismic" },
  ],
  webModules: [
    { name: "FrontCommerce", path: "front-commerce/src/web" },
+   {
+     name: "Prismic",
+     path: "./node_modules/front-commerce-prismic/prismic/web",
+   },
  ],
};

The module is ready!

You can now use the Prismic loader to Expose Prismic Content in your project.

Optional: update your CSP

If you plan to directly include images in your content, don’t forget to add the domain images.prismic.io to imgSrc in the contentSecurityPolicy configuration.

Optional: Configure the PrismicWysiwyg

If you are using any other Wysiwyg enabled modules, then you will need to override theme/modules/WysiwygV2/getWysiwygComponent.js and map all of the Wysiwyg customizations, for example:

const typenameMap = {
  CustomWysiwyg: loadable(() => import("./CustomWysiwyg")),
  PrismicWysiwyg: loadable(() => import("./PrismicWysiwyg")),
};

Refer to the Wysiwyg Customization to learn more.

Default transforms

• <script> tags with a supported embed script are transformed into theme/web/WysiwygV2/PrismicWysiwyg/EmbedScript components.