FastStore monorepo

Learn how to configure your FastStore project using the monorepo architecture for centralized storefront development.

FastStore monorepo is the unified repository model that centralizes the storefront development within VTEX.

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

The storefront is organized into modules, which are sets of pages that comprise the storefront. Each module represents a primary functional area of the ecommerce storefront experience within 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.
Checkout: Handles the purchase and payment process and provides customization for checkout logic, UI, and integration points to ensure a seamless buying experience.
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.

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

Monorepo structure

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.

`faststore.json` file

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

Each account object has at least one of the following keys: discovery, checkout, and sales-app. Each of these keys maps to a module configuration object with the following fields:

Field	Type	Description	Example	Usage	Required
`path`	`string`	Path to the given module customization	`"packages/store1"`	Local development, production build	✅
`port`	`number`	Port where the module will be available	`3001`	Local development	✅
`cli`	`string`	Argument to override the module CLI being used	`"custom-cli"`	Local development, production build	❌

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

faststore.json


_19{
_19  "$schema": "https://unpkg.com/@vtex/fsp-config/faststore.schema.json",
_19  "stores": {
_19    "account1": {
_19      "discovery": {
_19        "path": "packages/store1",
_19        "port": 3000
_19      },
_19      "checkout": {
_19        "path": "packages/checkout",
_19        "port": 3001
_19      },
_19      "sales-app": {
_19        "path": "packages/sales-app",
_19        "port": 3002
_19      }
_19    }
_19  }
_19}

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

Setting up your monorepo

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.

Open a terminal.
Navigate to your monorepo project folder.
Run npx @vtex/fsp-cli init --from-discovery to initialize your FastStore monorepo.
Run yarn install to install and update the project dependencies.
Open your FastStore monorepo project in any code editor of your choice and check that it's working.
Commit your changes and push them to the repository.

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

Monorepo structure

faststore.json file

Setting up your monorepo

`faststore.json` file