Skip to main content
Version: 2.x

Installation

This guide explains how to install and configure the Front-Commerce Prismic module to start interacting with an existing Prismic repository from your application.

This guide assumes that you are working in a Front-Commerce skeleton environment.

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.
tip

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.

Configure Front-Commerce to use the Prismic module​

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

.front-commerce.js
module.exports = {
  modules: [
    "./node_modules/front-commerce/modules/datasource-elasticsearch",
    "./node_modules/front-commerce/theme-chocolatine",
    "./node_modules/front-commerce/modules/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" }],
};

The module is ready!

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

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
}'
tip

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

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 getWysiwygComponent.js and map all of the Wysiwyg customizations, for example:

theme/modules/WysiwygV2/getWysiwygComponent.js
import loadable from "@loadable/component";

const DefaultWysiwyg = loadable(() =>
  import("theme/modules/WysiwygV2/DefaultWysiwyg")
);

const typenameMap = {
  MagentoWysiwyg: loadable(() =>
    import("theme/modules/WysiwygV2/MagentoWysiwyg/MagentoWysiwyg")
  ),
  PrismicWysiwyg: loadable(() =>
    import("theme/modules/WysiwygV2/PrismicWysiwyg")
  ),
};

const getWysiwygComponent = (type) => {
  return typenameMap[type] || DefaultWysiwyg;
};

export default getWysiwygComponent;

Refer to the Wysiwyg Customization to learn more.

Default transforms