FastStore Storefront — Coding Rules

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

• Every CMS Section must read all data it needs from Contexts or via BFF requests — no props are ever passed to new CMS sections
• Never change browser history or location directly — always rely on existing FastStore hooks
• Every section override must be registered in

  <project_root>/src/components/index.tsx

  with the same name defined in

  {project_root}/cms/faststore/schema.json

  $componentKey

  field
• The file

  <project_root>/src/components/index.tsx

  must use default export only — do not use named exports
• The file at

  <project_root>/cms/schema.json

  must not be edited. It's alway regenerated on every

  vtex content generate-chema

  script run

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
• Prefer existing CSS custom properties (design tokens) from FastStore; create a new variable only when needed

CMS Sync Rule

cms/faststore/components/*.jsonc

cms/faststore/pages/*.jsonc

1. Run

     vtex content generate-schema -o cms/faststore/schema.json -b vtex.faststore4

   to generate the final schema file.
2. Run

   vtex content upload-schema cms/faststore/schema.json

   to push final schema file to cms admin app.

Workflow

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

Response Format

Reference Files

src/

.faststore/

faststore dev

build

discovery.config.js

getOverriddenSection

src/components/index.tsx

Query

Mutation

StoreSort

StoreProduct

StoreCart

StoreSession

src/graphql/vtex/

src/graphql/thirdParty/

Server*

Client*

usePDP

useQuery

useLazyQuery

src/themes/custom-theme.scss

cms_component__*.jsonc

$componentKey

index.tsx

generate-schema

upload-schema

@faststore/sdk

sendAnalyticsEvent

useAnalyticsEvent

gtmContainerId

discovery.config.js

<head>

src/scripts/ThirdPartyScripts.tsx

discovery.config.js

Navbar

ProductDetails

getOverriddenSection

@faststore/ui

data-fs-*