Part 1: Configuring your VTEX account with the Headless CMS

FastStore Integrating your storefront with Headless CMS

Let's set up all the tools you need to integrate the Headless CMS with your FastStore project. First, we will install the VTEX IO CLI. The VTEX IO CLI will help you during your development process by allowing you to perform different actions in the VTEX platform. In the following, we will install and configure the Headless CMS app in your VTEX account.

Before you begin

Before you proceed with setting up the Headless CMS in your account, please ensure the following:

Installation of the Headless CMS and its dependencies

Ensure that you have installed the vtex.admin-cms@1.x and its dependencies as described in the FastStore requirements.

Successful FastStore Onboarding

Make sure the FastStore Onboarding process has been completed successfully. The Headless CMS is installed during this onboarding phase. For detailed instructions, please refer to the Starting a new FastStore project tutorial.

Changes made through Headless CMS in VTEX Admin, such as creating new content types, adding sections, and updating fields, might not automatically trigger deployments or be reflected in the store's GitHub history. This means these changes won't be published to your storefront and won't be visible to your customers. The workaround for this issue is to manually create a commit in your store GitHub repository to trigger the store build and be able to apply the changes made in the Headless CMS. See more details in the WebOps app is not fully integrated with Headless CMS Known Issue article.

Installation of VTEX IO CLI

Ensure that you have installed the VTEX IO CLI on your machine. This CLI is required to install the Headless CMS plugins and CMS dependencies. For more information, please refer to the Installing VTEX IO CLI guide.

Instructions

Step 1 - Setting up the command-line environment

Open the terminal and log in to your VTEX account using the VTEX IO CLI:

Remember to replace the values between curly brackets according to your account name.

_10vtex login {account}
Install the Headless CMS plugin:

_10vtex plugins install cms

Now, check if the installation of the Headless CMS plugin was successful by running vtex cms.

${"base64":" ","img":{"width":2142,"height":636,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":123285,"url":"https://vtexhelp.vtexassets.com/assets/docs/src/faststore-vtex-cms___460365970fb39c94e300b9fbd497e17e.png"}}$

Windows user: If you find problems while installing the plugin, please refer to the Troubleshooting article

macOS user: If you find problems, run yarn config set ignore-engines true to ignore the Node.js incompatibility version, then run vtex plugins install cms again.

Remember, we recommend using the latest Node.js version or a version higher than 15.0.0.

Step 2 - Configuring the Headless CMS

Let's configure the URLs of the webhooks used by the Headless CMS app.

In the VTEX Admin, access Storefront > Headless CMS.
In the FastStore project interface, click on Settings (⚙️).
In Settings, click the Build tab.
Fill the Preview URL field with your live store URL. This URL activates the button on Headless CMS so you can preview the changes made on a page.

_10https://{liveStoreId}.vtex.app/api/preview

Replace the values between curly brackets according to your live store ID from WebOps. To find the live store ID in, refer to the Live store ID instructions.
Fill in the Production base URL field with your store's endpoint to preview changes in the Headless CMS before publishing them. Replace the values between curly brackets according to your scenario.

_10https://{liveStoreId}.vtex.app
Click on SAVE.

Step 3 - Communicating WebOps updates to the Headless CMS

Now, if you are developing your FastStore project with CI/CD and Headless CMS, you must ensure that CI/CD is aware of every CMS update performed via the VTEX Admin. To do so, you must configure the WebOps webhooks responsible for communicating with the Headless CMS as in the following.

Open your FastStore project in any code editor of your preference.
Edit the faststore.config.js file in the root directory of your project.
In the Headless CMS configuration, add the webhookUrls property corresponding to your store website as in the following:

faststore.config.js
_10"vtexHeadlessCms": { _10 webhookUrls: [ _10 "https://{account}.myvtex.com/cms-releases/webhook-releases" _10 ] _10}
Open a Pull Request in your project including the previous changes.
Merge the Pull Request.

Now you can make changes to the Headless CMS and check if commits are being created in the project. In the following example, the Hero title was modified to 10% off on first purchase, and we can see that it generated a commit in the repository.

${"base64":" ","img":{"width":950,"height":441,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":110781,"url":"https://vtexhelp.vtexassets.com/assets/docs/src/cms-example-commits___7bb21be1504033098122feb013667b49.png"}}$