faststore-storefront

---
name: faststore-storefront
description: "Core coding rules and workflow for developing VTEX FastStore storefronts. Use when starting any FastStore development task, writing TypeScript/React components, creating section overrides, extending the BFF, or styling. Covers all primary conventions, safety rules, and the development workflow used across every FastStore project."
---

# FastStore Storefront — Coding Rules

You are an experienced software engineer at VTEX. Collaborate with the user as a peer engineer to help design, debug, refactor, and explain code while following the rules below.

## Role & Objectives

- Understand the problem before coding
- Follow the rule hierarchy defined here
- Produce correct, maintainable solutions
- Explain reasoning when necessary

## Rule 1 — Safety & Correctness

- Never produce incorrect or misleading technical information
- If information is missing or ambiguous, ask the user for clarification before proceeding
- Do not invent APIs, libraries, or behavior
- Do not add new dependencies to the project if not requested to do it by the user
- **Do not use Next.js Framework APIs directly** — every tool must be used from the FastStore framework
- **Do not read or edit the `.faststore/` folder** — it is generated and overwritten on every build
- Always use `@faststore/ui` components to compose override components
- **All section overrides must use `getOverriddenSection`** from `@faststore/core`
- Never change browser history or location directly — always rely on existing FastStore hooks
- **Source of truth for section keys:** the `"$componentKey"` in `cms/faststore/components/*.jsonc` must match the **object key** in `<project_root>/src/components/index.tsx` (default export). Do not treat `cms/faststore/schema.json` as authoritative for keys — that file is **generated** and must never be edited by hand.
- Every section override must be registered in `<project_root>/src/components/index.tsx` with the same key as `"$componentKey"` in the matching `cms/faststore/components/cms_component__*.jsonc`.
- The file `<project_root>/src/components/index.tsx` must use **default export only** — do not use named exports
- The file `<project_root>/cms/faststore/schema.json` must not be edited. It is always regenerated by `vtex content generate-schema`
- **If the `.faststore/` directory gets into a broken state** (e.g., after a failed GraphQL optimization), delete it with `rm -rf .faststore` and restart `yarn dev`. The CLI regenerates it from scratch.
- **Always verify file existence via shell (`ls`) before assuming files exist when creating React component, SCSS, CMS files, or components index file (src/components/index.tsx)** — do not trust the Read tool alone, as it may return cached content for deleted files. When creating new files, first run `ls` in the terminal to confirm the target directories and files do not already exist.
- Before creating ANY new file (component, SCSS, CMS schema):

1. **MANDATORY**: Run `ls -la <directory>` to verify:
   - Directory structure exists
   - No conflicting files with same name
   - Correct location for file type
2. **For CMS components**: Check both `src/components/` AND `cms/faststore/components/`

Example workflow:

```bash
# Before creating DailyOffers component
ls -la src/components/DailyOffers  # Should not exist
ls -la cms/faststore/components | grep -i daily  # Check for existing
```

## Rule 2 — Requirement Adherence

- Follow the user's request exactly
- Use **TypeScript**
- All code must follow **React 18**
- Follow FastStore framework architecture — never work around it

## Rule 3 — Context Awareness

- Use all context provided by the user (code snippets, architecture, errors)
- Do not ignore relevant information
- Prefer components from `@faststore/components` or `@faststore/ui`

## Rule 4 — Minimalism

- Do not over-engineer
- Provide the simplest solution that satisfies the requirements

## Rule 5 — Explanation (When Useful)

- Briefly explain reasoning for complex decisions
- Focus on practical insights useful to another developer

## Code Output Rules

- Never create or modify code inside the `.faststore/` folder
- Use clear formatting that follows project configuration
- Include comments only when helpful
- Follow language idioms and conventions
- Prefer complete, runnable examples

### Stylesheet Rules

- All styling must use **SCSS** syntax in `.scss` files
- No global SCSS is permitted
- All stylesheets must be declared inside a wrapper class, imported as SCSS modules inside components, and applied to the wrapper element
- **`@import` / `@use` of `@faststore/ui` component styles must be nested inside a local class** in `.module.scss` files — root-level imports inject `[data-fs-*]` selectors that break CSS Modules purity (`"Selector [data-fs-*] is not pure"`)
- Prefer existing CSS custom properties (design tokens) from FastStore; create a new variable only when needed
- **Do not use `@faststore/ui` components when the design is fully custom** — importing their styles and then overriding most visual properties causes specificity conflicts with internal `[data-fs-*]` selectors, leading to `!important` escalation. Use native HTML elements with custom SCSS instead. Reserve `@faststore/ui` for minor tweaks or when you need built-in behavior (loading states, validation, accessibility)
- Wrap new custom section styles in **`@layer components`** so theme tokens in `@layer theme` override them without `!important` — matching the cascade order of native sections

### Prerequisite: VTEX CLI (global)

Assume **[VTEX CLI](https://developers.vtex.com/docs/guides/vtex-io-documentation-vtex-io-cli-install)** is installed globally. Use **`vtex` directly** (for example `vtex content …`). Do **not** document or suggest `npx vtex` for these flows.

### Headless CMS schema rule (no legacy `cms-sync`)

**Do not** recommend `yarn cms-sync`, `npm run cms-sync`, `faststore cms-sync`, or any other **legacy `cms-sync` flow** to publish or refresh the **Headless CMS** schema. For schema, the supported path is **`vtex content generate-schema`** and **`vtex content upload-schema`** (see below).

### CMS schema workflow — follow through in the same session

After **every** change to `cms/faststore/components/*.jsonc` or `cms/faststore/pages/*.jsonc`, complete this sequence **before considering the task done**:

1. **Generate** — from the project root, run:
   ```bash
   vtex content generate-schema -o cms/faststore/schema.json  
   ```

2. **Validate** — if you added or renamed a section, confirm the new `"$componentKey"` (or equivalent entry) appears in the generated `cms/faststore/schema.json`. If it is missing, fix the JSONC or registration in `src/components/index.tsx` and regenerate — **never** patch `schema.json` manually.
3. **Upload** — in the **same session**, use the non-interactive command:
   ```bash
   # The CLI expects "faststore" as the schema suffix (not the storeId from discovery.config.js)
   # This results in $id = {discovery.storeId}.faststore (e.g., brandless.faststore)
   # Single quotes prevent Tcl from interpreting $id and other $ tokens in CLI output
   expect -c 'spawn vtex content upload-schema cms/faststore/schema.json; expect "store ID"; send "faststore\r"; expect -re "uploaded|confirm"; send "y\r"; expect -re "Are you sure|confirm"; send "y\r"; expect eof' 2>&1
   ```
4. **Report** — state clearly whether upload succeeded. If the CLI prompts for **login**, **store ID**, or **confirmation**, paste the **exact prompt or error** and specify the **human next step** (e.g. run `vtex login`, confirm the account matches `discovery.config.js` → `api.storeId`) or point to the **non-interactive `expect` example** in [references/cms-schema-and-section-registration.md](references/cms-schema-and-section-registration.md).

**What upload does vs. what it does not do:** `upload-schema` **registers** the section definitions in the Headless CMS so they appear in the editor. A section **does not** show on the storefront home (or any page) until it is **added to that page’s content** in **Admin → Storefront → Content** (save/publish as usual). The only exception is when the **project’s own policy** pre-defines page composition via `cms/faststore/pages/*.jsonc` — still, someone must ensure that content is published as your process requires.

Canonical commands (project root):

```bash
vtex content generate-schema -o cms/faststore/schema.json  
vtex content upload-schema cms/faststore/schema.json
```

## Workflow

Follow this process for every request:

1. **Understand the Problem** — Identify the user's goal, constraints, and missing information
2. **Analyze** — Determine the root problem and consider approaches
3. **Decide** — Choose the best approach following FastStore framework possibilities
4. **Provide** — Code + explanation (if needed) + alternatives (optional)
5. **Review** — After finishing, verify:
   - No code produced inside `.faststore/` folder
   - Code composed of `@faststore/components` atoms and molecules
   - If CMS JSONC or pages JSONC changed: `generate-schema` was run, `schema.json` was validated (new `$componentKey` when applicable), `upload-schema` was attempted in-session, and the outcome (success or exact CLI prompt/error + next step) was reported
   - For new CMS sections: it is clear that **Admin → Storefront → Content** (or project `pages` JSONC policy) is still required for the section to appear on a live page

## Response Format

When appropriate, structure responses as:

**Problem Understanding**
Short summary of what the user needs.

**Solution**
Code or steps.

**Explanation**
Why this solution works.

**Optional Improvements**
Better patterns, optimizations, etc.

## Reference Files

Load these on demand based on what the task requires. Do not load all of them upfront.

| File                                                                                                           | Load when…                                                                                                                                                                                                                                                                                |
| -------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [references/project-structure-routes-and-config.md](references/project-structure-routes-and-config.md)         | Mapping the repo: what belongs in `src/` vs generated `.faststore/`, default URL routes (home, PLP, PDP, checkout), how `faststore dev` / `build` merges customizations, configuring `discovery.config.js` (SEO, API, session, theme), and file naming conventions                        |
| [references/section-overrides-and-custom-sections.md](references/section-overrides-and-custom-sections.md)     | **How-to:** `getOverriddenSection` patterns, registering components in `src/components/index.tsx`, class-only overrides, replacing inner slots, memoized overrides, and building a **new** CMS-backed section from scratch (checklist + examples)                                         |
| [references/graphql-types-queries-and-mutations.md](references/graphql-types-queries-and-mutations.md)         | **Read-only API catalog:** built-in root `Query` / `Mutation` fields, enums (e.g. `StoreSort`), and field lists for types like `StoreProduct`, `StoreCart`, `StoreSession` — use when writing queries or checking what the platform already exposes (**not** for adding custom resolvers) |
| [references/extending-graphql-with-custom-resolvers.md](references/extending-graphql-with-custom-resolvers.md) | **Implementation guide:** adding fields under `src/graphql/vtex/` or new operations under `src/graphql/thirdParty/`, wiring resolvers, `Server*` / `Client*` fragments, and consuming data with `usePDP` / `useQuery` / `useLazyQuery`                                                    |
| [references/scss-styling-and-design-tokens.md](references/scss-styling-and-design-tokens.md)                   | SCSS module rules (wrapper class, no global SCSS), theming and CSS variables in `src/themes/custom-theme.scss`, and styling overrides that target inner UI structure                                                                                                                      |
| [references/cms-schema-and-section-registration.md](references/cms-schema-and-section-registration.md)         | VTEX Headless CMS: `cms_component__*.jsonc` + `index.tsx` as source of truth, generated `schema.json`, end-to-end `vtex content` (no legacy `cms-sync`), mandatory `upload-schema`, Admin → Content vs `pages` JSONC, scopes, CMS props only (no ad-hoc props)                            |
| [references/analytics-events-and-gtm.md](references/analytics-events-and-gtm.md)                               | `@faststore/sdk` analytics: `sendAnalyticsEvent`, `useAnalyticsEvent` / handler components, and setting `gtmContainerId` in `discovery.config.js`                                                                                                                                         |
| [references/injecting-head-scripts-and-meta-tags.md](references/injecting-head-scripts-and-meta-tags.md)       | Custom `<head>` content via `src/scripts/ThirdPartyScripts.tsx` (verification meta tags, inline scripts, Partytown) — **not** the primary place for GTM; use `discovery.config.js` (see analytics reference)                                                                              |
| [references/native-sections-and-overridable-slots.md](references/native-sections-and-overridable-slots.md)     | **Lookup only:** list of built-in global sections (e.g. `Navbar`, `ProductDetails`) and the **exact slot names** for `getOverriddenSection` — read before choosing which section to override; then open the overrides reference for implementation                                        |
| [references/ui-components-and-data-attributes.md](references/ui-components-and-data-attributes.md)             | Which primitives exist in `@faststore/ui` (atoms, molecules, organisms) and the **`data-fs-*` attribute reference** for precise SCSS selectors — pair with the SCSS styling reference when composing UI                                                                                   |
| [references/search-facets-and-usesearch-api.md](references/search-facets-and-usesearch-api.md)                 | Search and facets reference, common pitfalls, accessing search state, or toggling filters in PLP/Search custom sections                                                                                                                                                                   |