🎉 We are thrilled to introduce FastStore v2. If you are looking for documentation of the previous version of FastStore, please refer to FastStore v1.

Understanding the Project Structure

In the previous guide of this track, you started your first FastStore store, learned how to run a local server and made your first change in the storefront. Now it's time to understand how our project is structured.

By understanding the structure of a FastStore project, you can better navigate the codebase and make customizations to fit your specific needs.

Let's start taking a look at the structure that represents the source code of a FastStore project:

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


  • /.faststore - Manages and coordinates the FastStore project to deliver a functional starter store. It contains essential packages such as Components, SDK, and API, which provide the core functionality of the FastStore starter.

  • /src - Contains all of your store's customizations, including your custom components created through overriding and theme.

  • /src/themes - Keeps your store's theme, such as midnight.


  • custom-theme.scss - Holds the styling information for your store, controlling the graphic elements such as typography, colors, borders, and spacing that provide your store with a unique look and feel.

  • cypress.config.ts - Configures the options and preferences required for running tests with Cypress.

  • faststore.config.js - Configures aspects of the project such as SEO settings, store ID, and theme using this file. Keep in mind that some of these configurations are set during the FastStore Onboarding process. For more information on the configuration options available in this file, refer to Configuration options for faststore.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 - Stores environment variables that your application can access during runtime, such as API keys and database credentials.

  • 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 by Yarn based on the dependencies in your package.json file.


Defines the project's metadata and handles dependencies and scripts using yarn. Let's take a closer look at three important packages inside this file:

  • @faststore/core

Bundles FastStore source code, including the starter for FatsStore projects: starter store. It contains three sub-packages, Components, SDK, and API, which handle the starter.

  • @faststore/ui

Provides a design system based on FastStore components using Sass for styling.

  • @faststore/cli

Combines VTEX code (@faststore/core) with the customizations you make in your repository (/src). This package helps with debugging and differentiating between VTEX code and customizations. To learn more, refer to the FastStore CLI documentation.