1. Setting up your environment

Setting up your environment

Prepare your account and local setup to start developing with FastStore.

This is the first step in the FastStore track. In this guide, you’ll prepare your local environment and VTEX account to ensure reliable onboarding, builds, and CMS synchronization.

Skipping these prerequisites can lead to failed installations, duplicated content during onboarding, or local development errors.

Step 1. Installing the VTEX IO CLI

The VTEX IO CLI is the command-line interface used to manage your VTEX projects. If you haven’t already installed it, follow this guide to install it on your machine.

Step 2. Installing Headless CMS and its dependencies

Headless CMS is the native VTEX content management solution for FastStore projects. Before proceeding, ensure the following apps are installed in your account to avoid build errors or duplicated content:

vtex.admin-cms@1.x
vtex.admin-cms-graphql-rc

To check whether you have them installed, follow the instructions below:

Open the terminal and log in to your account using the following command. Replace {accountName} with your VTEX account name.

_10vtex login {accountName}
Run vtex ls to list all the installed apps in your account.
Check if vtex.admin-cms@1.x and vtex.admin-cms-graphql-rc are in the list. If so, proceed to the next step. Otherwise, follow these instructions.
After logging into your account, install vtex.admin-cms@1.x by running the following command:

_10vtex install vtex.admin-cms@1.x vtex.admin-cms-graphql-rc

A success message will confirm the installation:

${"base64":" ","img":{"width":2018,"height":486,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":122705,"url":"https://vtexhelp.vtexassets.com/assets/docs/src/cms-install___7144afabf5a895ba92905926808507b2.png"}}$

Step 3. Installing the Headless CMS plugins

To use the Headless CMS through the CLI, install its plugins:

Open the terminal and log in to your VTEX account using the VTEX IO CLI. Replace accountName with your VTEX account name.

_10vtex login {accountName}
Install the Headless CMS plugin:

_10vtex plugins install cms
Verify the installation by running the following command:

_10vtex 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 users: If you experience installation issues, refer to the Troubleshooting article.
macOS users: If you encounter problems, run yarn config set ignore-engines true to ignore the Node.js version incompatibility, then run vtex plugins install cms again.
We recommend using Node.js version 15.0.0 or higher.

Step 4. Enabling the VTEX Intelligent Search app

The VTEX Intelligent Search app enhances the user experience by providing accurate and personalized search results throughout the shopping journey. Before developing a storefront in FastStore, you need to enable the app in your account. For more information about Intelligent Search and its integration, please refer to the VTEX Intelligent Search and Integration Settings guides.

To enable the app, check which version of the Edition App is installed in your account.

Based on the edition version, follow the instructions below.

To confirm which Edition App version is installed in your account, open the terminal and use the VTEX IO CLI. Log in to your account by running vtex login {accountName} and run vtex edition get to see the Edition App version installed in the current account.

Accounts using the vtex.edition-store@5.x

If your account is using the vtex.edition-store@5.x major version, the VTEX Intelligent Search app is already included, and you must integrate it via VTEX Admin.

To integrate VTEX Intelligent Search, go to the VTEX Admin, access Store Settings > Intelligent Search > Integrations, and click START INTEGRATION.

Accounts using an edition version below 5.x

In the VTEX IO CLI, log in to your VTEX account by running vtex login {accountName}. Remember to replace the value between curly brackets with your account name.
If the VTEX Intelligent Search app is not installed in your account, run the following command to install it:

_10vtex install vtex.search-resolver@1.x vtex.admin-search@1.x

After successfully installing the app, access VTEX Admin, navigate to Store Settings > Intelligent Search > Integrations, and click START INTEGRATION.

Accounts wishing to migrate to the 5.x

If you are using a different major version and want to migrate, please open a ticket with VTEX Support and request the installation of the Edition Store vtex.edition-store@5.x.

Step 5. Installing the FastStore WebOps app

The FastStore WebOps app helps you create, deploy, and manage your FastStore projects. It also provides performance insights and deployment management tools.

The FastStore WebOps app only works in stores using the Edition Store. If your store uses the Edition Business, also known as using the Legacy CMS Portal technology, make sure to open a support ticket to change it to the Edition Store.

Once you have changed the edition, follow the instructions in this requirements guide.

To install the app, follow these steps.

In a terminal, log in to your VTEX account by running the following command. Replace {accountName} with your store account name, for example, vtex login store.

_10vtex login {accountName}
Install the FastStore WebOps app by running the following command:

_10vtex install vtex.webops

The FastStore WebOps app only works in the production environment, so you must install it exclusively in your account's master environment.
A confirmation message will appear. Type y to proceed.

_10? Are you sure you want to force this operation on the master workspace on the account store? » (y/N)

The FastStore WebOps app is now installed in your account. Refer to the FastStore WebOps app guide to create your first FastStore project.

Next step

Now that your environment is ready, learn how to access and use the WebOps app: 2. Setting up the FastStore WebOps app