Apply when building, customizing, or deploying extensions for VTEX Sales App. Covers the complete 7-step workflow from prerequisite checks through code generation to deployment, including extension points (cart, PDP, menu), React hooks (useCart, usePDP, useCartItem, useCurrentUser, useExtension), TypeScript types, secure API integration patterns, and API documentation ingestion (OpenAPI, URLs, or inline specs) to generate typed integrations.
Apply when building, customizing, or deploying extensions for VTEX Sales App. Covers the complete 7-step workflow from prerequisite checks through code generation to deployment, including extension points (cart, PDP, menu), React hooks (useCart, usePDP, useCartItem, useCurrentUser, useExtension), TypeScript types, secure API integration patterns, and API documentation ingestion (OpenAPI, URLs, or inline specs) to generate typed integrations.
Inside the FastStore project, a Sales App workspace must exist (typically at packages/sales-app) with src/, package.json, and tsconfig.json. Check root package.json"workspaces" for a path containing sales-app. If missing, STOP:
yarn add @vtex/sales-app -D -W
npx fsp create
# Prompts: account name → "Sales App" → path (default or custom)# Then add the path to root package.json "workspaces" array
yarn install
Constraint: Extension point names must match exactly
IDs are a fixed set. Non-existent names silently fail.
Why this matters
The extension renders nowhere. No build error — invisible at runtime.
Detection
Any name not in: cart.cart-list.after, cart.cart-item.after, cart.order-summary.after, pdp.sidebar.before, pdp.sidebar.after, pdp.content.after, menu.item, menu.drawer-content.
Step 1 — Discovery. Detect use case from keywords, ask follow-up questions, determine API auth strategy. If the user provides API documentation (URL, OpenAPI/Swagger file, Markdown, or inline text), ingest it to extract endpoint details and response shapes — skip the equivalent manual questions. Validate extracted information with the user. Load the discovery reference for detailed question flows and the API Documentation Ingestion section.
Step 2 — Map requirements to extension point + hooks + template. Present plan listing the files to be created: components/<ComponentName>.tsx, components/<ComponentName>.css (plain CSS — never.module.css), and index.tsx. Wait for approval.
Required references for this step (load before generating):
code-templates-and-patterns.md — all component templates, the CSS template (with the full Sales App design system inlined: tokens, typography, spacing, responsive), the index.tsx template, type generation rules, and the custom fetch hook pattern.
static-analysis-rules.md — sandbox security, CSS containment, and React performance rules from @vtex/fsp-analyzer. Run these checks on all generated files.
design-guidelines.md — load when the extension renders any UI text (sentence case rule) or uses icons (Phosphor Icons).
If API documentation was ingested in Step 1, generate TypeScript interfaces from the extracted response shapes and use them in the component instead of the ${DATA_INTERFACE} placeholder. If the extension calls 2+ endpoints, extract fetch logic into custom hook(s). Validate against the 12-point checklist in code-templates-and-patterns.md. Fix all violations before presenting code; surface warnings to the user.
Step 4 — Generate docs/<ExtensionName>.md inside the Sales App package (create the docs/ folder if needed). Load the documentation template reference for the required 9-section structure and the markdown skeleton to fill in.
Choosing an extension point, selecting hooks, looking up TypeScript types (CartItem, ProductSku, Totalizers, Attachment), or checking hook return values and availability per extension point
Generating extension code — simple, hook, API, IO Proxy, or Direct Auth templates; CSS template with the full Sales App design system inlined (tokens, typography, spacing, responsive); index.tsx with defineExtensions; hook initialization; validation checklist
Writing UI text (sentence case rule) or using icons (Phosphor Icons). CSS-related design rules — tokens, typography, spacing, responsive — are inlined directly in the CSS template inside code-templates-and-patterns.md, so this file is not needed for CSS generation.
Writing the docs/<ExtensionName>.md file in Step 4 — the 9-section structure and markdown skeleton
Common failure modes
Skipping prerequisite checks — Generating code without FastStore/Sales App installed. Always confirm both before Step 1.
Not presenting plan — User may want a different approach. Always confirm at Step 2 before generating code.
Skipping documentation — Extension generated without docs/<ExtensionName>.md. Load documentation-template.md for the required structure.
Inventing API response types — Generated interface doesn't match actual API. If documentation was provided, derive types from it; if not, ask the user for a sample JSON response.
Ignoring provided API documentation — User provided a URL or file but agent asked manual questions anyway. Always check for documentation first and use the API Documentation Ingestion flow.
Inline fetch with 2+ endpoints — Multiple fetch calls inside the component body. Extract into custom hook(s) in hooks/use{Purpose}.ts.
Placing code outside packages/sales-app/src/ — Files outside this path are not included in the build.
Code-level violations (DOM APIs, Node imports, eval, CSS containment, React performance, design tokens) are enforced by @vtex/fsp-analyzer and caught during Step 3 validation. See static-analysis-rules.md and design-guidelines.md.
All other code-level rules (sandbox APIs, CSS containment, React performance, design tokens) are enforced by @vtex/fsp-analyzer and checked during Step 3. See static-analysis-rules.md and design-guidelines.md.
