@thorprovider/create-thor-app 4.0.0 → 4.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +31 -68
- package/dist/index.js +158 -629
- package/package.json +1 -1
- package/templates/default/.agents/AGENTS.md +27 -0
- package/templates/default/.env.example +12 -33
- package/templates/default/.eslintrc.json +20 -27
- package/templates/default/README.md +60 -119
- package/templates/default/ai-validator.json +47 -29
- package/templates/default/app/api/revalidate/route.ts +27 -36
- package/templates/default/app/backend-unavailable/page.tsx +3 -7
- package/templates/default/app/error.tsx +1 -2
- package/templates/default/app/global-error.tsx +3 -3
- package/templates/default/app/globals.css +1 -71
- package/templates/default/app/layout.tsx +16 -38
- package/templates/default/app/not-found.tsx +1 -1
- package/templates/default/app/page.tsx +45 -113
- package/templates/default/components/providers/app-providers.tsx +19 -68
- package/templates/default/components/providers/cart-provider.tsx +155 -0
- package/templates/default/components/providers/commerce-provider.tsx +34 -0
- package/templates/default/components/providers/region-provider.tsx +115 -0
- package/templates/default/docs/README.md +52 -37
- package/templates/default/docs/commerce-api.md +58 -125
- package/templates/default/docs/patterns.md +128 -67
- package/templates/default/docs/project-structure.md +58 -50
- package/templates/default/docs/rules.md +44 -42
- package/templates/default/docs/types.md +105 -1024
- package/templates/default/lib/commerce.ts +52 -135
- package/templates/default/lib/env.ts +68 -94
- package/templates/default/lib/utils.ts +18 -0
- package/templates/default/next.config.ts +7 -0
- package/templates/default/package.json +2 -8
- package/templates/default/registry.json +6 -0
- package/templates/default/styles/tokens.css +81 -0
- package/templates/default/components/providers/navigation-provider.tsx +0 -37
- package/templates/default/config/site.config.ts +0 -156
- package/templates/default/docs/components.md +0 -282
- package/templates/default/docs/dependencies.md +0 -61
- package/templates/default/lib/auth-context.tsx +0 -213
- package/templates/default/lib/cart-provider.tsx +0 -53
- package/templates/default/lib/commerce-provider.tsx +0 -48
- package/templates/default/lib/region-detection.ts +0 -73
- package/templates/default/lib/region-provider.tsx +0 -53
- package/templates/default/lib/regions-config.ts +0 -48
- package/templates/default/lib/storefront-config.ts +0 -54
- package/templates/default/next.config.mjs +0 -51
- package/templates/default/proxy.ts +0 -155
- package/templates/default/scripts/generate-regions-config.ts +0 -498
package/package.json
CHANGED
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
# Thor Commerce Storefront
|
|
2
|
+
|
|
3
|
+
## CRITICAL
|
|
4
|
+
ALWAYS import from @thorprovider/types — NEVER define Product, Cart, Collection, Money.
|
|
5
|
+
|
|
6
|
+
## Imports
|
|
7
|
+
- Types: import type { Product, Cart, Collection, Money } from '@thorprovider/types'
|
|
8
|
+
- Data: import { commerce } from '@/lib/commerce' (server)
|
|
9
|
+
- Prices: formatPrice(money) from @/lib/utils — NEVER render amount raw
|
|
10
|
+
- Nav: next/link and next/image directly
|
|
11
|
+
|
|
12
|
+
## Type Facts
|
|
13
|
+
- Product.title (NOT name), Product.featuredImage?.url (NOT thumbnail)
|
|
14
|
+
- Money.amount is decimal STRING ("29.99"), currencyCode "USD"
|
|
15
|
+
- variant.price is ONE Money (not array). product.handle for URLs.
|
|
16
|
+
|
|
17
|
+
## Client Hooks
|
|
18
|
+
- useCart() — @/components/providers/cart-provider
|
|
19
|
+
- useRegion() — @/components/providers/region-provider
|
|
20
|
+
- useCommerce() — @/components/providers/commerce-provider
|
|
21
|
+
|
|
22
|
+
## Stack
|
|
23
|
+
Next.js 16, React 19, TS strict, Tailwind 4, shadcn/ui.
|
|
24
|
+
Server Components default. 'use client' only for interactivity.
|
|
25
|
+
|
|
26
|
+
## Docs
|
|
27
|
+
docs/types.md (types), docs/patterns.md (examples).
|
|
@@ -1,56 +1,35 @@
|
|
|
1
1
|
# ============================================================================
|
|
2
|
-
# Thor Commerce
|
|
2
|
+
# Thor Commerce — Environment Configuration
|
|
3
3
|
# ============================================================================
|
|
4
|
-
# Copy this file to .env and fill in your values.
|
|
4
|
+
# Copy this file to .env.local and fill in your values.
|
|
5
5
|
# ============================================================================
|
|
6
6
|
|
|
7
7
|
# ---------------------------------------------------------------------------
|
|
8
|
-
# Commerce Backend (
|
|
8
|
+
# Commerce Backend (optional)
|
|
9
9
|
# ---------------------------------------------------------------------------
|
|
10
|
-
# Which commerce platform to use: medusa | shopify | bigcommerce | custom
|
|
11
|
-
|
|
12
|
-
|
|
10
|
+
# Which commerce platform to use: mock | medusa | shopify | bigcommerce | custom
|
|
11
|
+
# Use `mock` to design/layout the storefront before a real backend is connected.
|
|
12
|
+
NEXT_PUBLIC_COMMERCE_PROVIDER=mock
|
|
13
|
+
|
|
14
|
+
# Your commerce backend API URL (required for real backends, ignored in mock mode)
|
|
13
15
|
NEXT_PUBLIC_COMMERCE_API_URL=http://localhost:9000
|
|
16
|
+
|
|
17
|
+
# Publishable API key for your commerce backend (required for real backends, ignored in mock mode)
|
|
14
18
|
NEXT_PUBLIC_COMMERCE_API_KEY=your-publishable-api-key
|
|
15
19
|
|
|
16
20
|
# ---------------------------------------------------------------------------
|
|
17
|
-
# Default Currency
|
|
21
|
+
# Default Currency (required)
|
|
18
22
|
# ---------------------------------------------------------------------------
|
|
19
23
|
NEXT_PUBLIC_DEFAULT_CURRENCY=USD
|
|
20
24
|
|
|
21
|
-
# ---------------------------------------------------------------------------
|
|
22
|
-
# Health Check
|
|
23
|
-
# ---------------------------------------------------------------------------
|
|
24
|
-
# Path used by proxy.ts to verify backend availability.
|
|
25
|
-
# Example for Medusa: /store/regions
|
|
26
|
-
# Consult your backend provider's API docs for the appropriate endpoint.
|
|
27
|
-
HEALTH_CHECK_PATH=/store/regions
|
|
28
|
-
|
|
29
|
-
# ---------------------------------------------------------------------------
|
|
30
|
-
# Region Script Retry Policy
|
|
31
|
-
# ---------------------------------------------------------------------------
|
|
32
|
-
REGIONS_SCRIPT_MAX_RETRIES=3
|
|
33
|
-
REGIONS_SCRIPT_RETRY_DELAY=1000
|
|
34
|
-
REGIONS_SCRIPT_RETRY_MAX_DELAY=10000
|
|
35
|
-
REGIONS_SCRIPT_RETRY_BACKOFF=2
|
|
36
|
-
|
|
37
|
-
# ---------------------------------------------------------------------------
|
|
38
|
-
# Admin API (optional)
|
|
39
|
-
# ---------------------------------------------------------------------------
|
|
40
|
-
# COMMERCE_ADMIN_EMAIL=admin@example.com
|
|
41
|
-
# COMMERCE_ADMIN_PASSWORD=your-admin-password
|
|
42
|
-
# COMMERCE_ADMIN_API_URL=http://localhost:9000
|
|
43
|
-
# COMMERCE_ADMIN_TOKEN_TTL_MS=3600000
|
|
44
|
-
|
|
45
25
|
# ---------------------------------------------------------------------------
|
|
46
26
|
# Sales Channel (optional — multi-tenant stores)
|
|
47
27
|
# ---------------------------------------------------------------------------
|
|
48
28
|
# NEXT_PUBLIC_SALES_CHANNEL_ID=sc_01...
|
|
49
29
|
|
|
50
30
|
# ---------------------------------------------------------------------------
|
|
51
|
-
# Webhook Revalidation (optional —
|
|
31
|
+
# Webhook Revalidation (optional — ISR cache busting from backend)
|
|
52
32
|
# ---------------------------------------------------------------------------
|
|
53
33
|
# Shared secret used by the backend to authenticate webhook calls.
|
|
54
34
|
# Must match the FRONTEND_WEBHOOK_SECRET configured in the Medusa backend.
|
|
55
35
|
# FRONTEND_WEBHOOK_SECRET=your-shared-webhook-secret
|
|
56
|
-
|
|
@@ -1,43 +1,36 @@
|
|
|
1
1
|
{
|
|
2
2
|
"extends": ["next/core-web-vitals", "plugin:@typescript-eslint/recommended"],
|
|
3
3
|
"rules": {
|
|
4
|
-
//
|
|
5
|
-
|
|
4
|
+
// Prevent hardcoded colors — require CSS variables for dark mode + theming
|
|
5
|
+
"no-restricted-syntax": [
|
|
6
|
+
"error",
|
|
7
|
+
{
|
|
8
|
+
"selector": "ObjectExpression > Property[key.name='color'][value.type='Literal'][value.value=/^#[0-9a-fA-F]+$/]",
|
|
9
|
+
"message": "Hardcoded hex colors are not allowed. Use CSS custom properties via style={{ color: 'var(--color-name)' }} or Tailwind tokens (text-foreground, bg-primary, etc.) instead."
|
|
10
|
+
}
|
|
11
|
+
],
|
|
12
|
+
|
|
13
|
+
// Prevent importing from packages NOT in dependencies
|
|
6
14
|
"no-restricted-imports": [
|
|
7
15
|
"error",
|
|
8
16
|
{
|
|
9
17
|
"patterns": [
|
|
10
18
|
{
|
|
11
|
-
"group": ["
|
|
12
|
-
"message": "
|
|
13
|
-
"importNames": ["default"]
|
|
19
|
+
"group": ["@thorprovider/components", "@thorprovider/components/*"],
|
|
20
|
+
"message": "This template does NOT use @thorprovider/components. Use shadcn/ui components from @/components/ui/ instead."
|
|
14
21
|
},
|
|
15
22
|
{
|
|
16
|
-
"group": ["
|
|
17
|
-
"
|
|
18
|
-
|
|
19
|
-
|
|
23
|
+
"group": ["@thorprovider/providers", "@thorprovider/providers/*"],
|
|
24
|
+
"message": "This template does NOT use @thorprovider/providers. Providers are local code in @/components/providers/ and @/lib/."
|
|
25
|
+
},
|
|
26
|
+
{
|
|
27
|
+
"group": ["@medusajs/*", "@shopify/*", "@bigcommerce/*"],
|
|
28
|
+
"message": "Never import backend SDKs directly. Use the commerce singleton from @/lib/commerce instead."
|
|
20
29
|
}
|
|
21
30
|
]
|
|
22
31
|
}
|
|
23
32
|
],
|
|
24
33
|
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
"no-restricted-syntax": [
|
|
28
|
-
"error",
|
|
29
|
-
{
|
|
30
|
-
"selector": "ObjectExpression > Property[key.name='color'][value.type='Literal'][value.value=/^#[0-9a-fA-F]+$/]",
|
|
31
|
-
"message": "Hardcoded hex colors are not allowed. Use CSS custom properties via style={{ color: 'var(--color-name)' }} instead."
|
|
32
|
-
}
|
|
33
|
-
]
|
|
34
|
-
},
|
|
35
|
-
"overrides": [
|
|
36
|
-
{
|
|
37
|
-
"files": ["app/global-error.tsx"],
|
|
38
|
-
"rules": {
|
|
39
|
-
"no-restricted-imports": "off"
|
|
40
|
-
}
|
|
41
|
-
}
|
|
42
|
-
]
|
|
34
|
+
"@typescript-eslint/no-unused-expressions": "off"
|
|
35
|
+
}
|
|
43
36
|
}
|
|
@@ -1,157 +1,98 @@
|
|
|
1
1
|
---
|
|
2
|
-
title:
|
|
3
|
-
purpose:
|
|
4
|
-
|
|
2
|
+
title: "@thorprovider/core"
|
|
3
|
+
purpose: "V0-native storefront template for Thor Commerce Builder"
|
|
4
|
+
lastReviewed: "2026-05-01"
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
-
#
|
|
7
|
+
# @thorprovider/core v2.0.0
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
V0-native storefront template for Thor Commerce Builder. Lean scaffold designed for V0 AI code generation.
|
|
10
10
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
## 🚀 Development Workflow
|
|
11
|
+
## Architecture
|
|
14
12
|
|
|
15
|
-
|
|
13
|
+
**2 npm dependencies** — everything else is local code V0 can read:
|
|
16
14
|
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
# With backend pre-configured
|
|
22
|
-
yarn create:app --name my-store \
|
|
23
|
-
--commerce-provider medusa \
|
|
24
|
-
--commerce-api-url https://your-backend.com \
|
|
25
|
-
--commerce-api-key pk_live_xxx \
|
|
26
|
-
--preset electro \
|
|
27
|
-
--site-url https://my-store.com \
|
|
28
|
-
--generate-regions
|
|
29
|
-
|
|
30
|
-
cd projects/my-store
|
|
31
|
-
```
|
|
15
|
+
| Package | Purpose |
|
|
16
|
+
|---------|---------|
|
|
17
|
+
| `@thorprovider/types` | TypeScript interfaces (Product, Cart, Money, etc.) |
|
|
18
|
+
| `@thorprovider/adapters` | Commerce adapter factory (Medusa, Shopify, BigCommerce, etc.) |
|
|
32
19
|
|
|
33
|
-
|
|
34
|
-
-
|
|
35
|
-
-
|
|
36
|
-
- Generates `.env` from `.env.example` (backend flags inject values directly)
|
|
37
|
-
- Patches `config/site.config.ts` with `--preset` and `--site-url` if provided
|
|
38
|
-
- Optionally runs region generation (`--generate-regions`) to pre-populate `lib/regions-config.ts`
|
|
39
|
-
- Initializes git with an initial commit
|
|
40
|
-
- Generates `.v0-context.md` (contains frozen architecture files)
|
|
20
|
+
**NOT used** (by design):
|
|
21
|
+
- `@thorprovider/components` — V0 creates UI from shadcn/ui (unique UI per client)
|
|
22
|
+
- `@thorprovider/providers` — providers are local code (V0 can read source)
|
|
41
23
|
|
|
42
|
-
|
|
43
|
-
```bash
|
|
44
|
-
nano .env
|
|
45
|
-
# Set: NEXT_PUBLIC_COMMERCE_API_URL=https://your-backend.com
|
|
46
|
-
# NEXT_PUBLIC_COMMERCE_API_KEY=pk_live_xxx
|
|
47
|
-
```
|
|
24
|
+
## Quick Start
|
|
48
25
|
|
|
49
|
-
**Test locally:**
|
|
50
26
|
```bash
|
|
27
|
+
cp .env.example .env.local
|
|
28
|
+
yarn install
|
|
51
29
|
yarn dev
|
|
52
30
|
# → http://localhost:3000
|
|
53
31
|
```
|
|
54
32
|
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
1. Create a new repo on GitHub (without README, .gitignore, or license)
|
|
58
|
-
2. In your local app directory, add the remote and push:
|
|
59
|
-
|
|
60
|
-
```bash
|
|
61
|
-
git remote add origin https://github.com/your-org/your-repo.git
|
|
62
|
-
git branch -M main
|
|
63
|
-
git push -u origin main
|
|
33
|
+
Default runtime:
|
|
64
34
|
```
|
|
65
|
-
|
|
66
|
-
This repository is auto-generated by `create:app` from `@thorprovider/core`—it contains frozen architecture files that **must not be modified manually**. See "Frozen Files" below.
|
|
67
|
-
|
|
68
|
-
### Step 3: Use V0 for Feature Development
|
|
69
|
-
|
|
70
|
-
1. **Copy `.v0-context.md`** (in this repo root) into your first message on [v0.app](https://v0.app)
|
|
71
|
-
2. **Connect your GitHub repo** to V0 (V0 will pull from the remote)
|
|
72
|
-
3. **Paste the entire `.v0-context.md`** — it tells V0 which files are frozen and which patterns to follow
|
|
73
|
-
4. **Describe your feature** in subsequent messages (e.g., "Add product filters to the product list page")
|
|
74
|
-
5. **V0 generates code** respecting the frozen architecture and `@thorprovider/*` package constraints
|
|
75
|
-
6. **Review the PR**, merge to main, and deploy to Vercel
|
|
76
|
-
|
|
77
|
-
Example first message on v0.app:
|
|
35
|
+
NEXT_PUBLIC_COMMERCE_PROVIDER=mock
|
|
78
36
|
```
|
|
79
|
-
[Paste full .v0-context.md here]
|
|
80
37
|
|
|
81
|
-
|
|
38
|
+
Live backend environment (only required when using a real provider):
|
|
39
|
+
```
|
|
40
|
+
NEXT_PUBLIC_COMMERCE_API_URL=https://your-backend.com
|
|
41
|
+
NEXT_PUBLIC_COMMERCE_API_KEY=pk_live_xxx
|
|
82
42
|
```
|
|
83
43
|
|
|
84
|
-
###
|
|
44
|
+
### Runtime modes
|
|
85
45
|
|
|
86
|
-
|
|
46
|
+
- `mock` or missing live-backend env vars → storefront uses fixture-backed mock commerce data
|
|
47
|
+
- real provider + API URL + API key → storefront uses the live backend immediately
|
|
48
|
+
- switching config later should not require rewriting app code that calls `commerce.*`, `useCart()`, or `useRegion()`
|
|
87
49
|
|
|
88
|
-
|
|
50
|
+
## Development with V0
|
|
89
51
|
|
|
90
|
-
|
|
52
|
+
1. Push this repo to GitHub
|
|
53
|
+
2. Connect to V0 (`v0.dev` → New Project → Import GitHub repo)
|
|
54
|
+
3. V0 auto-discovers `AGENTS.md` for architecture context
|
|
55
|
+
4. Describe features — V0 generates code respecting frozen architecture
|
|
91
56
|
|
|
92
|
-
|
|
57
|
+
## Frozen Files (Do NOT Modify)
|
|
93
58
|
|
|
94
59
|
| File | Purpose |
|
|
95
60
|
|------|---------|
|
|
96
|
-
| `lib/commerce.ts` | Commerce
|
|
97
|
-
| `lib/
|
|
98
|
-
| `lib/
|
|
99
|
-
| `
|
|
100
|
-
| `lib/cart-provider.tsx` | CartProvider context wrapper |
|
|
101
|
-
| `lib/storefront-config.ts` | Backend-driven storefront config fetch (theme accent, cached) |
|
|
102
|
-
| `lib/region-detection.ts` | IP-based region detection from Vercel/Cloudflare geolocation headers |
|
|
103
|
-
| `components/providers/app-providers.tsx` | Provider hierarchy (order is critical) |
|
|
104
|
-
| `components/providers/navigation-provider.tsx` | NavigationProvider wrapper |
|
|
105
|
-
| `app/layout.tsx` | Root layout (ThemeProvider + AppProviders + IP region detection) |
|
|
106
|
-
| `config/site.config.ts` | Site configuration (values can change, shape is frozen) |
|
|
107
|
-
|
|
108
|
-
**Why frozen?** Changing these breaks the L1–L5 architecture. If you need to modify one, you're likely breaking a constraint. Read `docs/rules.md` first.
|
|
109
|
-
|
|
110
|
-
---
|
|
61
|
+
| `lib/commerce.ts` | Commerce singleton (createProvider + lazy proxy) |
|
|
62
|
+
| `lib/env.ts` | Zod-validated environment schema |
|
|
63
|
+
| `lib/storefront-config.ts` | Backend-driven storefront config |
|
|
64
|
+
| `components/providers/app-providers.tsx` | Provider chain (order is critical) |
|
|
111
65
|
|
|
112
66
|
## What's Pre-Configured
|
|
113
67
|
|
|
114
|
-
-
|
|
115
|
-
-
|
|
116
|
-
-
|
|
117
|
-
-
|
|
118
|
-
-
|
|
119
|
-
- Webhook ISR revalidation (
|
|
120
|
-
-
|
|
68
|
+
- Commerce singleton with adapter-based backend access (retry built-in)
|
|
69
|
+
- Mock-first runtime that works without a live backend
|
|
70
|
+
- Shopping cart (persistent, backend-synced)
|
|
71
|
+
- Authentication (JWT)
|
|
72
|
+
- Dark mode + CSS token theming + backend-driven accent color
|
|
73
|
+
- Webhook ISR revalidation (opt-in via `FRONTEND_WEBHOOK_SECRET`)
|
|
74
|
+
- Error boundaries (page-level + global)
|
|
121
75
|
|
|
122
|
-
##
|
|
76
|
+
## Documentation
|
|
123
77
|
|
|
124
|
-
|
|
78
|
+
Read order for V0 / AI agents:
|
|
125
79
|
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
80
|
+
1. `docs/README.md` — Quick import reference
|
|
81
|
+
2. `docs/types.md` — All domain type shapes
|
|
82
|
+
3. `docs/commerce-api.md` — All `commerce.*` method signatures
|
|
83
|
+
4. `docs/patterns.md` — Code templates (pages, components, styling)
|
|
84
|
+
5. `docs/rules.md` — Non-negotiable constraints
|
|
85
|
+
6. `docs/project-structure.md` — Folder map + file ownership
|
|
130
86
|
|
|
131
|
-
|
|
87
|
+
## Tech Stack
|
|
132
88
|
|
|
133
|
-
|
|
134
|
-
-
|
|
135
|
-
-
|
|
136
|
-
-
|
|
137
|
-
-
|
|
138
|
-
|
|
139
|
-
**Then read `docs/` in order:**
|
|
140
|
-
1. [docs/project-structure.md](docs/project-structure.md)
|
|
141
|
-
2. [docs/dependencies.md](docs/dependencies.md) — 55 available components
|
|
142
|
-
3. [docs/types.md](docs/types.md) — Product, Cart, Order, Customer, Address shapes
|
|
143
|
-
4. [docs/commerce-api.md](docs/commerce-api.md) — getProducts(), createCart(), etc.
|
|
144
|
-
5. [docs/patterns.md](docs/patterns.md) — Server/client, fetch patterns
|
|
145
|
-
6. [docs/rules.md](docs/rules.md) — Non-negotiable constraints
|
|
89
|
+
- Next.js 16 (App Router)
|
|
90
|
+
- React 19
|
|
91
|
+
- TypeScript (strict)
|
|
92
|
+
- Tailwind CSS 4
|
|
93
|
+
- shadcn/ui (installed per-project via CLI)
|
|
146
94
|
|
|
147
95
|
## Deployment
|
|
148
96
|
|
|
149
|
-
**Vercel:** Connect repo → set env vars
|
|
150
|
-
|
|
151
|
-
**Self-hosted:** `yarn build && yarn start` with env vars set in host.
|
|
152
|
-
|
|
153
|
-
## Troubleshooting
|
|
154
|
-
|
|
155
|
-
**`Module not found: @thorprovider/*`** → Verify `NODE_AUTH_TOKEN` has `read:packages` scope, then `yarn install`.
|
|
156
|
-
|
|
157
|
-
**Backend unavailable / circuit breaker** → Check `NEXT_PUBLIC_COMMERCE_API_URL` and network connectivity. Auto-resets after 60s.
|
|
97
|
+
**Vercel:** Connect repo → set env vars → deploy.
|
|
98
|
+
**Self-hosted:** `yarn build && yarn start`
|
|
@@ -1,21 +1,10 @@
|
|
|
1
1
|
{
|
|
2
|
-
"version": "
|
|
3
|
-
"description": "V0 Stop Hooks validation criteria for Thor Commerce
|
|
2
|
+
"version": "2.0.0",
|
|
3
|
+
"description": "V0 Stop Hooks validation criteria for Thor Commerce V0-native template",
|
|
4
4
|
"maxRetries": 2,
|
|
5
|
-
"retryModelId": "v0-
|
|
5
|
+
"retryModelId": "v0-mini",
|
|
6
|
+
"postStreamDelayMs": 2000,
|
|
6
7
|
"architecturalRules": [
|
|
7
|
-
{
|
|
8
|
-
"id": "no-next-link-in-components",
|
|
9
|
-
"filePattern": "components/**/*.tsx",
|
|
10
|
-
"pattern": "import.*Link.*from.*next/link|from\\s+['\"]next/link['\"]",
|
|
11
|
-
"description": "Never import next/link in components/ — use useNavigation() from @thorprovider/providers instead"
|
|
12
|
-
},
|
|
13
|
-
{
|
|
14
|
-
"id": "no-next-image-in-components",
|
|
15
|
-
"filePattern": "components/**/*.tsx",
|
|
16
|
-
"pattern": "import.*Image.*from.*next/image|from\\s+['\"]next/image['\"]",
|
|
17
|
-
"description": "Never import next/image in components/ — use useNavigation() which provides a framework-aware Image component"
|
|
18
|
-
},
|
|
19
8
|
{
|
|
20
9
|
"id": "no-backend-sdk-imports",
|
|
21
10
|
"filePattern": "**/*.{ts,tsx}",
|
|
@@ -28,13 +17,6 @@
|
|
|
28
17
|
"pattern": "fetch\\(.*NEXT_PUBLIC_COMMERCE_API_URL|fetch\\(.*process\\.env\\.NEXT_PUBLIC_COMMERCE_API",
|
|
29
18
|
"description": "Never call the commerce backend directly via fetch — use commerce.* methods from @/lib/commerce"
|
|
30
19
|
},
|
|
31
|
-
{
|
|
32
|
-
"id": "circuit-breaker-on-reads",
|
|
33
|
-
"filePattern": "app/**/*.{ts,tsx}",
|
|
34
|
-
"pattern": "await commerce\\.get(?!.*backendCircuitBreaker)",
|
|
35
|
-
"description": "All commerce.get*() read operations must be wrapped with backendCircuitBreaker.execute(fn, fallback)",
|
|
36
|
-
"required": true
|
|
37
|
-
},
|
|
38
20
|
{
|
|
39
21
|
"id": "no-hardcoded-hex-colors",
|
|
40
22
|
"filePattern": "components/**/*.tsx",
|
|
@@ -91,16 +73,52 @@
|
|
|
91
73
|
"description": "Error handlers must capture errors (not empty catch blocks)"
|
|
92
74
|
},
|
|
93
75
|
{
|
|
94
|
-
"id": "no-
|
|
76
|
+
"id": "no-raw-money-render",
|
|
95
77
|
"filePattern": "**/*.tsx",
|
|
96
|
-
"pattern": "\\
|
|
97
|
-
"description": "
|
|
78
|
+
"pattern": "\\{.*\\.amount\\}|\\{.*\\.price\\.amount\\}|\\$\\{.*\\.amount\\}",
|
|
79
|
+
"description": "Never render Money.amount directly — use formatPrice() from @/lib/utils (Money.amount is a decimal string like '29.99', not a displayable value)"
|
|
98
80
|
},
|
|
99
81
|
{
|
|
100
|
-
"id": "
|
|
101
|
-
"filePattern": "
|
|
102
|
-
"pattern": "
|
|
103
|
-
"description": "
|
|
82
|
+
"id": "use-featured-image-not-thumbnail",
|
|
83
|
+
"filePattern": "**/*.tsx",
|
|
84
|
+
"pattern": "product\\.thumbnail|product\\.image(?!s)",
|
|
85
|
+
"description": "Use product.featuredImage?.url for the main product image (not .thumbnail or .image)"
|
|
86
|
+
},
|
|
87
|
+
{
|
|
88
|
+
"id": "use-title-not-name",
|
|
89
|
+
"filePattern": "**/*.tsx",
|
|
90
|
+
"pattern": "product\\.name(?![s])",
|
|
91
|
+
"description": "Use product.title (not product.name) — @thorprovider/types uses 'title'"
|
|
92
|
+
},
|
|
93
|
+
{
|
|
94
|
+
"id": "price-is-singular-not-array",
|
|
95
|
+
"filePattern": "**/*.tsx",
|
|
96
|
+
"pattern": "variant\\.prices\\[|variants\\[.*\\]\\.prices",
|
|
97
|
+
"description": "ProductVariant.price is a single Money object (not an array). Use variant.price.amount, not variant.prices[0]"
|
|
98
|
+
},
|
|
99
|
+
{
|
|
100
|
+
"id": "use-thorprovider-types",
|
|
101
|
+
"filePattern": "**/*.{ts,tsx}",
|
|
102
|
+
"pattern": "interface\\s+Product\\s*\\{|type\\s+Product\\s*=",
|
|
103
|
+
"description": "Import Product type from @thorprovider/types — never redefine it locally"
|
|
104
|
+
},
|
|
105
|
+
{
|
|
106
|
+
"id": "use-commerce-singleton",
|
|
107
|
+
"filePattern": "app/**/*.{ts,tsx}",
|
|
108
|
+
"pattern": "createProvider\\(",
|
|
109
|
+
"description": "Never call createProvider() in app/ — import commerce from @/lib/commerce (singleton)"
|
|
110
|
+
},
|
|
111
|
+
{
|
|
112
|
+
"id": "no-thorprovider-components-import",
|
|
113
|
+
"filePattern": "**/*.{ts,tsx}",
|
|
114
|
+
"pattern": "from\\s+['\"]@thorprovider/components['\"]|from\\s+['\"]@thorprovider/providers['\"]",
|
|
115
|
+
"description": "Do not import from @thorprovider/components or @thorprovider/providers — use local providers from @/components/providers/ and shadcn/ui for UI"
|
|
116
|
+
},
|
|
117
|
+
{
|
|
118
|
+
"id": "use-format-price",
|
|
119
|
+
"filePattern": "**/*.tsx",
|
|
120
|
+
"pattern": "parseFloat\\(.*\\.amount\\)|Number\\(.*\\.amount\\)|parseInt\\(.*\\.amount\\)",
|
|
121
|
+
"description": "Use formatPrice() from @/lib/utils instead of manually parsing Money.amount"
|
|
104
122
|
}
|
|
105
123
|
]
|
|
106
124
|
}
|
|
@@ -1,64 +1,55 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Webhook Revalidation Route
|
|
3
3
|
*
|
|
4
|
-
* Receives webhook events from the
|
|
5
|
-
*
|
|
6
|
-
*
|
|
7
|
-
* Events handled:
|
|
8
|
-
* - `site_config.updated` — revalidates site-config tag
|
|
9
|
-
* - `storefront_config.updated` — revalidates storefront-config tag
|
|
10
|
-
* - `sales_channel.updated` — revalidates all
|
|
4
|
+
* Receives webhook events from the commerce backend and triggers
|
|
5
|
+
* ISR revalidation for affected pages/tags.
|
|
11
6
|
*
|
|
12
7
|
* Security: Validates `x-webhook-secret` header against FRONTEND_WEBHOOK_SECRET.
|
|
13
8
|
*/
|
|
14
9
|
|
|
15
|
-
import { revalidatePath, revalidateTag } from 'next/cache'
|
|
16
|
-
import { NextRequest, NextResponse } from 'next/server'
|
|
10
|
+
import { revalidatePath, revalidateTag } from 'next/cache'
|
|
11
|
+
import { NextRequest, NextResponse } from 'next/server'
|
|
17
12
|
|
|
18
13
|
export async function POST(req: NextRequest) {
|
|
19
|
-
const expectedSecret = process.env.FRONTEND_WEBHOOK_SECRET
|
|
14
|
+
const expectedSecret = process.env.FRONTEND_WEBHOOK_SECRET
|
|
20
15
|
|
|
21
|
-
// Reject if secret is not configured — endpoint is effectively disabled
|
|
22
16
|
if (!expectedSecret) {
|
|
23
|
-
return NextResponse.json({ message: 'Webhook not configured' }, { status: 503 })
|
|
17
|
+
return NextResponse.json({ message: 'Webhook not configured' }, { status: 503 })
|
|
24
18
|
}
|
|
25
19
|
|
|
26
|
-
const secret = req.headers.get('x-webhook-secret')
|
|
27
|
-
|
|
20
|
+
const secret = req.headers.get('x-webhook-secret')
|
|
28
21
|
if (!secret || secret !== expectedSecret) {
|
|
29
|
-
return NextResponse.json({ message: 'Unauthorized' }, { status: 401 })
|
|
22
|
+
return NextResponse.json({ message: 'Unauthorized' }, { status: 401 })
|
|
30
23
|
}
|
|
31
24
|
|
|
32
|
-
let body: { event?: string
|
|
25
|
+
let body: { event?: string }
|
|
33
26
|
try {
|
|
34
|
-
body = await req.json()
|
|
27
|
+
body = await req.json()
|
|
35
28
|
} catch {
|
|
36
|
-
return NextResponse.json({ message: 'Invalid JSON body' }, { status: 400 })
|
|
29
|
+
return NextResponse.json({ message: 'Invalid JSON body' }, { status: 400 })
|
|
37
30
|
}
|
|
38
31
|
|
|
39
|
-
const event = body.event ?? 'unknown'
|
|
32
|
+
const event = body.event ?? 'unknown'
|
|
40
33
|
|
|
41
34
|
// Revalidate cache tags based on event type
|
|
42
35
|
switch (event) {
|
|
43
|
-
case '
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
revalidateTag('storefront-config', 'max');
|
|
52
|
-
break;
|
|
36
|
+
case 'product.updated':
|
|
37
|
+
case 'product.created':
|
|
38
|
+
case 'product.deleted':
|
|
39
|
+
revalidateTag('products', 'max')
|
|
40
|
+
break
|
|
41
|
+
case 'collection.updated':
|
|
42
|
+
revalidateTag('collections', 'max')
|
|
43
|
+
break
|
|
53
44
|
default:
|
|
54
|
-
// Unknown event — revalidate
|
|
55
|
-
revalidateTag('
|
|
56
|
-
revalidateTag('
|
|
57
|
-
break
|
|
45
|
+
// Unknown event — revalidate all commerce data
|
|
46
|
+
revalidateTag('products', 'max')
|
|
47
|
+
revalidateTag('collections', 'max')
|
|
48
|
+
break
|
|
58
49
|
}
|
|
59
50
|
|
|
60
|
-
//
|
|
61
|
-
revalidatePath('/')
|
|
51
|
+
// Always revalidate root for any webhook
|
|
52
|
+
revalidatePath('/')
|
|
62
53
|
|
|
63
|
-
return NextResponse.json({ revalidated: true, event })
|
|
54
|
+
return NextResponse.json({ revalidated: true, event })
|
|
64
55
|
}
|
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Backend Unavailable Page
|
|
3
3
|
*
|
|
4
|
-
* Shown when the
|
|
5
|
-
* Self-contained — zero dependency on providers
|
|
4
|
+
* Shown when the commerce backend is unreachable (e.g. via middleware or error boundary redirect).
|
|
5
|
+
* Self-contained — zero dependency on providers because the
|
|
6
6
|
* provider chain itself may be what failed.
|
|
7
7
|
*
|
|
8
8
|
* Privacy:
|
|
@@ -63,11 +63,7 @@ export default async function BackendUnavailablePage({
|
|
|
63
63
|
<code className="bg-background px-1 rounded text-[11px]">.env.local</code>
|
|
64
64
|
</li>
|
|
65
65
|
<li>Confirm the backend server is running and reachable</li>
|
|
66
|
-
<li>
|
|
67
|
-
Check <code className="bg-background px-1 rounded text-[11px]">HEALTH_CHECK_PATH</code> matches
|
|
68
|
-
a valid endpoint on your backend
|
|
69
|
-
</li>
|
|
70
|
-
<li>The circuit breaker auto-resets after 60 seconds</li>
|
|
66
|
+
<li>The retry system will automatically recover once the backend is back</li>
|
|
71
67
|
</ul>
|
|
72
68
|
</div>
|
|
73
69
|
)}
|
|
@@ -3,8 +3,7 @@
|
|
|
3
3
|
/**
|
|
4
4
|
* Error Boundary
|
|
5
5
|
*
|
|
6
|
-
* Catches errors thrown inside app
|
|
7
|
-
* (RegionProvider, AuthProvider, CartProvider failures).
|
|
6
|
+
* Catches errors thrown inside the app (provider chain failures, data fetch errors).
|
|
8
7
|
*
|
|
9
8
|
* Self-contained — does not import from @/components/ so it can render
|
|
10
9
|
* even when the component tree that caused the error cannot.
|
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
*
|
|
4
4
|
* Catches catastrophic errors in root layout (provider failures, StorefrontConfigError,
|
|
5
5
|
* missing environment variables).
|
|
6
|
-
* MUST include <html> and <body> tags —
|
|
6
|
+
* MUST include <html> and <body> tags — AppProviders may have crashed.
|
|
7
7
|
*
|
|
8
8
|
* Implements 3-step error pattern:
|
|
9
9
|
* 1. Categorize — SetupRequired | StorefrontConfig | generic
|
|
@@ -11,7 +11,7 @@
|
|
|
11
11
|
* 3. Display — sanitized UI, no env var names exposed in production
|
|
12
12
|
*
|
|
13
13
|
* Inline styles are intentional: this boundary cannot depend on CSS custom properties
|
|
14
|
-
* defined by
|
|
14
|
+
* defined by the layout (which may be the root cause of the crash).
|
|
15
15
|
* Colors are defined as RGB constants (not hex) to maintain consistency with design tokens.
|
|
16
16
|
*/
|
|
17
17
|
'use client'
|
|
@@ -19,7 +19,7 @@
|
|
|
19
19
|
import { useEffect } from 'react'
|
|
20
20
|
|
|
21
21
|
// FROZEN: Color tokens for error boundary (RGB format to match token system)
|
|
22
|
-
// These must remain inline since
|
|
22
|
+
// These must remain inline since the layout CSS may have crashed
|
|
23
23
|
const ERROR_COLORS = {
|
|
24
24
|
setupRequired: 'rgb(59, 130, 246)', // Blue-500 (Setup / config missing)
|
|
25
25
|
configError: 'rgb(249, 158, 11)', // Amber-500 (StorefrontConfigError)
|