FastStore monorepo

FastStore monorepo is the unified repository model that centralizes development of storefront modules on VTEX.

This architecture centralizes code, dependencies, and configuration for multiple projects in a single repository, enabling consistent customization, streamlined collaboration, and efficient code reuse.

The storefront experience is organized into modules, which are sets of pages that comprise a functional area of the ecommerce experience on VTEX. We support three modules:

• Product Discovery Experience: Covers the main customer-facing browsing flows, such as homepage, product listing pages (PLPs), search, product detail pages (PDPs), and custom content pages. It enables buyers to efficiently explore and discover products. In faststore.json, this module is the discovery key.
• Buyer Portal Checkout: Handles the purchase and payment process and provides customization for Buyer Portal Checkout logic, UI, and integration points to ensure a seamless buying experience. Use this module for Buyer Portal Checkout Extensibility.
• Sales App: Designed for assisted sales and in-store experiences. It supports use cases where sales representatives interact with buyers (for example, in physical stores), helping them complete purchases on behalf of customers. Use this module for VTEX Sales App Extensibility.

You don't need to use FastStore as your storefront to work with a FastStore monorepo. The Product Discovery Experience (discovery) module is optional. Configure only the modules you use. For example, you can include Buyer Portal Checkout and/or Sales App in the monorepo while using a different storefront, such as Store Framework.

In this guide, you'll learn how to set up a FastStore monorepo.

A FastStore monorepo doesn't require a rigid folder structure. You can organize your code as needed, as long as you keep a faststore.json file at the root of the repository. This file guides both local development and production deployments. See how to initialize a monorepo with @vtex/fsp-cli in the Setting up your monorepo section.

In local development, the faststore.json file acts as a configuration entry point. It consolidates the definitions and settings required for the unified repository and its storefront modules.

For production deployments, the faststore.json file guides the deployment process via FastStore WebOps. It ensures that the correct settings and configurations are applied when deploying storefront customizations to live environments. This file facilitates the transition from a local development setup to a production-ready application by supporting necessary parameters, such as paths and ports for each module.

The root of the faststore.json object contains a stores key. In stores, each key should be an account name.

Each account object must include at least one of the following keys: discovery, checkout, and sales-app. You can use any combination of these keys. You don't need a discovery key if FastStore isn't your storefront.

Each of these keys maps to a module configuration object with the following fields:

The following example shows a faststore.json file setup for a single store using multiple modules:

The following example shows a faststore.json file for an account that uses Sales App without FastStore as the storefront (discovery isn't declared):

You can see more examples of faststore.json configuration in the Monorepo use cases guide.

If your FastStore project uses FastStore WebOps and is hosted in vtex-sites or in your own GitHub organization, and you want to move to a FastStore monorepo, follow the instructions in the guide Moving your FastStore project to a new GitHub repository before setting up your monorepo.

To set up your monorepo, run @vtex/fsp-cli to generate the required monorepo configuration files and update your project structure.

1. Open a terminal.
2. Navigate to your monorepo project folder.
3. Run npx @vtex/fsp-cli init --from-discovery to initialize your FastStore monorepo. Use this command when you already have a Product Discovery Experience project. If you aren't using FastStore as your storefront, add only the modules you need with fsp create after the monorepo is set up. See Creating new projects.
4. Run yarn install to install and update the project dependencies.
5. Open your FastStore monorepo project in a code editor and check that it's working.
6. Commit your changes and push them to the repository.

If you encounter errors during the process, open a ticket with VTEX Support.