Understanding the Project Structure
In the previous guide of this track, you started your first FastStore project, learned how to run a local server, and made your first changes to the storefront. Now, it is time to understand how a FastStore 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:
_14/_14|-- /.faststore_14|-- /src_14 |-- /themes_14 |-- custom-theme.scss_14|-- cypress.config.ts_14|-- faststore.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.
Files
-
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 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 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- Holds 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 based on the dependencies in yourpackage.jsonfile.
package.json
Defines the project's metadata and handles dependencies and scripts using Yarn. Let's take a closer look at five important packages declared in this file:
@faststore/core
Bundles FastStore source code, including the FatsStore starter:
starter store. It contains four sub-packages, Components, SDK, UI and API, which handle the starter.@faststore/sdk
Handles all meaningful states an ecommerce store might have, such as:
| SDK states | Description |
|---|---|
| Session | Handles auth, region, locale, and currency data. |
| Cart | Handles a store cart's addition, remotion, update, and current state. |
| Component | Handles the state of the components of a store (e.g., display/hide mini cart). |
| Search | Handles 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
Gathers the design system based on FastStore components, using Sass for styling. For more information, refer to the FastStore UI guide.
Although the components use Sass, you can work with 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.