Menu
Guides
API Reference
App Development
Storefront Development
VTEX IO Apps
Troubleshooting
Release Notes
Storefront Development
Getting started with storefront solutions
FastStore
Store Framework
CMS Portal (Legacy)
Storefront best practices

4. Understanding the project structure

Learn how the FastStore project is organized, including its main directories, configurations, and code architecture.

3 min read
In this step, you'll learn how a FastStore project is organized and why it matters. Understanding the folder layout and key files helps you navigate the codebase, make targeted changes, and avoid misconfigurations as you customize your store.
Here's the structure that represents the source code of a FastStore project:

_14
/
_14
|-- /.faststore
_14
|-- /src
_14
|-- /themes
_14
|-- custom-theme.scss
_14
|-- cypress.config.ts
_14
|-- discovery.config.js
_14
|-- next-env.d.ts
_14
|-- package.json
_14
|-- README.md
_14
|-- tsconfig.json
_14
|-- vercel.json
_14
|-- vtex.env
_14
|-- yarn.lock

Folders

  • /.faststore - Manages and coordinates the FastStore project to deliver a functional starter store. This folder, also known as @faststore/core, provides the core functionality of the FastStore starter.
  • /src - Contains all of your store's customizations, including your custom components and theme.
  • /themes - Keeps your store's theme, such as midnight.

Files

  • custom-theme.scss - Holds the styling information for your store, controlling the graphic elements such as typography, colors, borders, and spacing that give your store with a unique look and feel.
  • cypress.config.ts - Configures the options and preferences required for running tests with Cypress.
  • discovery.config.js - Configures aspects of the project such as SEO preferences, VTEX account options, and theme. Note that these configurations are set during the onboarding process, reducing the need for changes to this file. For more information on configuration options for this file, refer to Configuration options for discovery.config.js.
  • next-env.d.ts - Generates a TypeScript definition file for Next.js.
  • tsconfig.json - Configures the compiler options and project settings for TypeScript, including target version, module resolution, and source file locations.
  • vtex.env - Defines the environment variables your project uses in local development. It isn't used to configure deployed environments. Don't store secrets, such as API keys, in this file. The production store domain comes from storeUrl in discovery.config.js and from the Host setting in FastStore WebOps, so you don't need an environment variable for it. If your own code needs variables or secrets in production, add them in WebOps under Settings > Variables and Secrets. For more information, see Managing variables and secrets.
  • yarn.lock - Locks down the exact versions of your project's dependencies, including transitive dependencies, to ensure consistent builds across different machines and environments. This file is automatically generated based on the dependencies in your package.json file.

package.json

Defines the project metadata and manages dependencies and scripts with Yarn. Key packages include:

@faststore/core

Bundles FastStore source code, including the starter store. It contains four sub-packages: components, sdk, ui, and api.

@faststore/sdk

Handles all meaningful states an ecommerce store might have, such as:
SDK statesDescription
SessionHandles auth, region, locale, and currency data.
CartHandles a store cart's addition, remotion, update, and current state.
ComponentHandles the state of the components of a store (e.g., display/hide mini cart).
SearchHandles the state of the faceted search (e.g., apply filters and sort).
The SDKs also provide GA4-compatible analytics functions to help you create powerful analytics capabilities in your ecommerce.

@faststore/ui

Provides the design system used by FastStore components, using Sass for styling. For more information, refer to the FastStore UI guide.
Although the components use Sass, you can style them using the desired tool for styling.

@faststore/api

Connects your project to your favorite ecommerce provider by creating interfaces for querying products, collections, and handling carts.

@faststore/cli

Provides scripts for building, running, debugging, and deploying your FastStore project. This package helps with debugging and differentiating between VTEX code and customizations. To learn more, refer to the FastStore CLI documentation.

Next step

Now that you understand your project structure, learn how to work with CMS in your project: 5. Working with CMS