Commerce Storefront
Scaffold storefronts and add commerce features using StateSet tools.
How It Works
- Choose a template (Next.js, Remix, Vite, Astro).
- Generate the project scaffold with
stateset-create.
- Add pages, components, and API routes via MCP or CLI.
- Configure
.env with database path and API keys.
- Seed demo data and run the dev server.
Usage
- CLI:
stateset-create <name> --template nextjs
- MCP tools: scaffold MCP server for adding pages/components.
- Keep database path in
.env and use @stateset/embedded on the server.
Permissions
- Read:
stateset-create --list, scaffold preview — no --apply needed.
- Write:
stateset-create, add-page, seed — requires --apply.
Examples
stateset-create my-storefront --template nextjs
stateset storefront add-page --project my-storefront --page products
stateset storefront seed --project my-storefront --data demo
stateset storefront dev --project my-storefront --port 3000
Configuration
| Template |
Framework |
SSR |
Use Case |
nextjs |
Next.js |
Yes |
Full-featured commerce site |
remix |
Remix |
Yes |
Data-heavy commerce apps |
vite |
Vite + React |
No |
SPAs and dashboards |
astro |
Astro |
Partial |
Content-heavy catalogs |
Output
{"status":"created","project":"my-storefront","template":"nextjs","path":"/home/user/my-storefront","pages":["index","products","cart","checkout"],"db_path":"./commerce.db","api_key_status":"configured","customer_id":"cust_001","email":"admin@example.com","sku":"WIDGET-001","tracking":"enabled"}
Present Results to User
- Project path, template used, and framework version.
- Pages and components added with file paths.
- How to run the dev server (
npm run dev).
- Environment variables that need to be set.
Troubleshooting
- Missing Node dependencies: run
npm install in the project directory.
- Database errors: confirm
.env DATABASE_PATH points to a writable file.
- Port conflict: change the dev server port in
package.json or use --port.
- Template not found: verify the template name matches available options and check status in the scaffold log.
Error Codes
TEMPLATE_NOT_FOUND: The specified storefront template name does not match any available option.DATABASE_PATH_INVALID: The .env DATABASE_PATH is missing or points to a non-writable location.PORT_CONFLICT: The requested dev server port is already in use; choose a different port.
Related Skills
- commerce-checkout — checkout flow logic for storefront pages
- commerce-products — product catalog data for storefront display
- commerce-embedded-sdk —
@stateset/embedded SDK used server-side
References
- references/storefront-templates.md
- /home/dom/stateset-icommerce/cli/.claude/skills/commerce-storefront/SKILL.md
- /home/dom/stateset-icommerce/cli/src/scaffold-server.js
1---2name: commerce-storefront3description: Build and adapt storefront templates and Agentic Commerce Protocol flows. Use when scaffolding storefront pages, designing checkout UI, or building ACP commerce flows.4---56# Commerce Storefront78Scaffold storefronts and add commerce features using StateSet tools.910## How It Works11121. Choose a template (Next.js, Remix, Vite, Astro).132. Generate the project scaffold with `stateset-create`.143. Add pages, components, and API routes via MCP or CLI.154. Configure `.env` with database path and API keys.165. Seed demo data and run the dev server.1718## Usage1920- CLI: `stateset-create <name> --template nextjs`21- MCP tools: scaffold MCP server for adding pages/components.22- Keep database path in `.env` and use `@stateset/embedded` on the server.2324## Permissions2526- Read: `stateset-create --list`, scaffold preview — no `--apply` needed.27- Write: `stateset-create`, `add-page`, `seed` — requires `--apply`.2829## Examples3031```bash32stateset-create my-storefront --template nextjs33stateset storefront add-page --project my-storefront --page products34stateset storefront seed --project my-storefront --data demo35stateset storefront dev --project my-storefront --port 300036```3738## Configuration3940| Template | Framework | SSR | Use Case |41|----------|-----------|-----|----------|42| `nextjs` | Next.js | Yes | Full-featured commerce site |43| `remix` | Remix | Yes | Data-heavy commerce apps |44| `vite` | Vite + React | No | SPAs and dashboards |45| `astro` | Astro | Partial | Content-heavy catalogs |4647## Output4849```json50{"status":"created","project":"my-storefront","template":"nextjs","path":"/home/user/my-storefront","pages":["index","products","cart","checkout"],"db_path":"./commerce.db","api_key_status":"configured","customer_id":"cust_001","email":"admin@example.com","sku":"WIDGET-001","tracking":"enabled"}51```5253## Present Results to User5455- Project path, template used, and framework version.56- Pages and components added with file paths.57- How to run the dev server (`npm run dev`).58- Environment variables that need to be set.5960## Troubleshooting6162- Missing Node dependencies: run `npm install` in the project directory.63- Database errors: confirm `.env` `DATABASE_PATH` points to a writable file.64- Port conflict: change the dev server port in `package.json` or use `--port`.65- Template not found: verify the template name matches available options and check status in the scaffold log.6667## Error Codes6869- `TEMPLATE_NOT_FOUND`: The specified storefront template name does not match any available option.70- `DATABASE_PATH_INVALID`: The `.env` `DATABASE_PATH` is missing or points to a non-writable location.71- `PORT_CONFLICT`: The requested dev server port is already in use; choose a different port.7273## Related Skills7475- commerce-checkout — checkout flow logic for storefront pages76- commerce-products — product catalog data for storefront display77- commerce-embedded-sdk — `@stateset/embedded` SDK used server-side7879## References80- references/storefront-templates.md81- /home/dom/stateset-icommerce/cli/.claude/skills/commerce-storefront/SKILL.md82- /home/dom/stateset-icommerce/cli/src/scaffold-server.js
stateset