Monorepo use cases
Explore common FastStore monorepo layouts and example faststore.json setups for single accounts, multiple stores, and shared code.
A FastStore monorepo can support different storefront modules, such as Product Discovery Experience, Buyer Portal Checkout, and VTEX Sales App, to meet the merchant's needs. You don't need to include the Product Discovery Experience (discovery) module if FastStore isn't your storefront.
This guide outlines common repository structures for these scenarios and provides example faststore.json configurations for each one. These examples can help organize your monorepo based on your implementation requirements.
The following sections cover:
- Single account with multiple modules: A single VTEX account using more than one storefront module.
- Buyer Portal Checkout and Sales App without Product Discovery: A FastStore monorepo that customizes Buyer Portal Checkout and/or Sales App while using a different storefront.
- Multiple brands or stores sharing code: Multiple accounts or subaccounts using the same monorepo while sharing common code.
- Multiple brands or stores with multiple modules: A monorepo where each account or subaccount can use multiple storefront modules with its own configuration.
Single account with multiple modules
In this scenario, one VTEX account uses multiple storefront modules, each with its own directory within the monorepo.
Basic directory structure
_10📂 Account monorepo_10│_10├── 📂 packages_10│ ├── 📂 discovery_10│ ├── 📂 checkout_10│ └── 📂 sales-app_10├── 📄 faststore.json_10├── 📄 package.json_10│
faststore.json configuration example
Buyer Portal Checkout and Sales App without Product Discovery
In this scenario, the account uses a FastStore monorepo for Buyer Portal Checkout and/or Sales App, but FastStore isn't the storefront. Omit the discovery key and declare only the modules you use.
After the monorepo is configured, set up the modules you included: Setting up Buyer Portal Checkout and Setting up Sales App extensions.
Basic directory structure
_10📂 Account monorepo_10│_10├── 📂 packages_10│ ├── 📂 checkout_10│ └── 📂 sales-app_10├── 📄 faststore.json_10├── 📄 package.json_10│
faststore.json configuration example
Multiple brands or stores sharing code
In this scenario, a merchant has multiple brands or stores, each mapped to a different account or subaccount, yet all share the same FastStore monorepo.
With separate repositories, sharing code between brands or stores usually depends on publishing npm packages or copying files between projects. In a FastStore monorepo, each brand or store has its own directory within a single repository, and shared code lives in dedicated folders that can be imported wherever needed. This setup avoids duplicating code across repositories and makes it easier to maintain consistent implementations across storefronts.
Basic directory structure
_10📂 Account monorepo_10│_10├── 📂 packages_10│ ├── 📂 store1_10│ └── 📂 store2_10├── 📄 faststore.json_10├── 📄 package.json_10│
faststore.json configuration example
Multiple brands or stores with multiple modules
In this scenario, a merchant has multiple brands or stores, and each of them can use more than one storefront module. All brands or stores share the same FastStore monorepo, but each has its own directory and module configuration.
Basic directory structure
_12📂 Account monorepo_12│_12├── 📂 packages_12│ └── 📂 store1_12│ ├── 📂 discovery_12│ └── 📂 checkout_12│ └── 📂 store2_12│ ├── 📂 discovery_12│ └── 📂 checkout_12├── 📄 faststore.json_12├── 📄 package.json_12│