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 nameFRONT_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 applicationFRONT_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 URLhttps://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
(orfront-commerce:prismic*
to include more specific namespaces) can be added to theDEBUG
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 intotheme/web/WysiwygV2/PrismicWysiwyg/EmbedScript
components.