@thorprovider/create-thor-app 3.1.3 → 4.0.1
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 +6 -55
- package/dist/index.js +154 -626
- package/package.json +2 -2
- package/templates/default/.agents/AGENTS.md +27 -0
- package/templates/default/.env.example +8 -30
- package/templates/default/.eslintrc.json +20 -27
- package/templates/default/README.md +52 -123
- 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 +10 -119
- package/templates/default/components/providers/app-providers.tsx +19 -68
- package/templates/default/components/providers/cart-provider.tsx +143 -0
- package/templates/default/components/providers/commerce-provider.tsx +33 -0
- package/templates/default/components/providers/region-provider.tsx +105 -0
- package/templates/default/docs/README.md +46 -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 +43 -42
- package/templates/default/docs/types.md +105 -1024
- package/templates/default/lib/commerce.ts +33 -132
- package/templates/default/lib/env.ts +24 -94
- package/templates/default/lib/utils.ts +18 -0
- package/templates/default/next-env.d.ts +1 -1
- 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
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@thorprovider/create-thor-app",
|
|
3
|
-
"version": "
|
|
4
|
-
"description": "CLI to scaffold a new Thor Commerce application
|
|
3
|
+
"version": "4.0.1",
|
|
4
|
+
"description": "CLI to scaffold a new Thor Commerce V0-native application",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": "./dist/index.js",
|
|
7
7
|
"main": "dist/index.js",
|
|
@@ -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,7 +1,7 @@
|
|
|
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
|
# ---------------------------------------------------------------------------
|
|
@@ -9,48 +9,26 @@
|
|
|
9
9
|
# ---------------------------------------------------------------------------
|
|
10
10
|
# Which commerce platform to use: medusa | shopify | bigcommerce | custom
|
|
11
11
|
NEXT_PUBLIC_COMMERCE_PROVIDER=medusa
|
|
12
|
-
|
|
12
|
+
|
|
13
|
+
# Your commerce backend API URL
|
|
13
14
|
NEXT_PUBLIC_COMMERCE_API_URL=http://localhost:9000
|
|
15
|
+
|
|
16
|
+
# Publishable API key for your commerce backend
|
|
14
17
|
NEXT_PUBLIC_COMMERCE_API_KEY=your-publishable-api-key
|
|
15
18
|
|
|
16
19
|
# ---------------------------------------------------------------------------
|
|
17
|
-
# Default Currency
|
|
20
|
+
# Default Currency (required)
|
|
18
21
|
# ---------------------------------------------------------------------------
|
|
19
22
|
NEXT_PUBLIC_DEFAULT_CURRENCY=USD
|
|
20
23
|
|
|
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
24
|
# ---------------------------------------------------------------------------
|
|
46
25
|
# Sales Channel (optional — multi-tenant stores)
|
|
47
26
|
# ---------------------------------------------------------------------------
|
|
48
27
|
# NEXT_PUBLIC_SALES_CHANNEL_ID=sc_01...
|
|
49
28
|
|
|
50
29
|
# ---------------------------------------------------------------------------
|
|
51
|
-
# Webhook Revalidation (optional —
|
|
30
|
+
# Webhook Revalidation (optional — ISR cache busting from backend)
|
|
52
31
|
# ---------------------------------------------------------------------------
|
|
53
32
|
# Shared secret used by the backend to authenticate webhook calls.
|
|
54
33
|
# Must match the FRONTEND_WEBHOOK_SECRET configured in the Medusa backend.
|
|
55
34
|
# 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,86 @@
|
|
|
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
|
-
|
|
11
|
+
## Architecture
|
|
12
12
|
|
|
13
|
-
|
|
13
|
+
**2 npm dependencies** — everything else is local code V0 can read:
|
|
14
14
|
|
|
15
|
-
|
|
15
|
+
| Package | Purpose |
|
|
16
|
+
|---------|---------|
|
|
17
|
+
| `@thorprovider/types` | TypeScript interfaces (Product, Cart, Money, etc.) |
|
|
18
|
+
| `@thorprovider/adapters` | Commerce adapter factory (Medusa, Shopify, BigCommerce, etc.) |
|
|
16
19
|
|
|
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
|
-
```
|
|
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)
|
|
32
23
|
|
|
33
|
-
|
|
34
|
-
- Clones `@thorprovider/core` into `projects/my-store/`
|
|
35
|
-
- Installs dependencies
|
|
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)
|
|
24
|
+
## Quick Start
|
|
41
25
|
|
|
42
|
-
**Configure your backend** (if you didn't use CLI flags):
|
|
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
|
-
```
|
|
48
|
-
|
|
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
|
+
Required environment:
|
|
64
34
|
```
|
|
65
|
-
|
|
66
|
-
|
|
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_API_URL=https://your-backend.com
|
|
36
|
+
NEXT_PUBLIC_COMMERCE_API_KEY=pk_live_xxx
|
|
78
37
|
```
|
|
79
|
-
[Paste full .v0-context.md here]
|
|
80
38
|
|
|
81
|
-
|
|
82
|
-
```
|
|
83
|
-
|
|
84
|
-
### Step 4: Deploy
|
|
85
|
-
|
|
86
|
-
After merging changes to main, deployment happens automatically (if you've connected Vercel).
|
|
39
|
+
## Development with V0
|
|
87
40
|
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
41
|
+
1. Push this repo to GitHub
|
|
42
|
+
2. Connect to V0 (`v0.dev` → New Project → Import GitHub repo)
|
|
43
|
+
3. V0 auto-discovers `AGENTS.md` for architecture context
|
|
44
|
+
4. Describe features — V0 generates code respecting frozen architecture
|
|
91
45
|
|
|
92
|
-
|
|
46
|
+
## Frozen Files (Do NOT Modify)
|
|
93
47
|
|
|
94
48
|
| File | Purpose |
|
|
95
49
|
|------|---------|
|
|
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
|
-
---
|
|
50
|
+
| `lib/commerce.ts` | Commerce singleton (createProvider + lazy proxy) |
|
|
51
|
+
| `lib/env.ts` | Zod-validated environment schema |
|
|
52
|
+
| `lib/storefront-config.ts` | Backend-driven storefront config |
|
|
53
|
+
| `components/providers/app-providers.tsx` | Provider chain (order is critical) |
|
|
111
54
|
|
|
112
55
|
## What's Pre-Configured
|
|
113
56
|
|
|
114
|
-
-
|
|
115
|
-
- Shopping cart (persistent, backend-synced
|
|
116
|
-
- Authentication (JWT
|
|
117
|
-
- Dark mode + CSS token theming + backend-driven accent color
|
|
118
|
-
-
|
|
119
|
-
-
|
|
120
|
-
- `@thorprovider/components` UI library (55 accessible components)
|
|
121
|
-
|
|
122
|
-
## 📚 Documentation
|
|
57
|
+
- Commerce singleton with adapter-based backend access (retry built-in)
|
|
58
|
+
- Shopping cart (persistent, backend-synced)
|
|
59
|
+
- Authentication (JWT)
|
|
60
|
+
- Dark mode + CSS token theming + backend-driven accent color
|
|
61
|
+
- Webhook ISR revalidation (opt-in via `FRONTEND_WEBHOOK_SECRET`)
|
|
62
|
+
- Error boundaries (page-level + global)
|
|
123
63
|
|
|
124
|
-
|
|
64
|
+
## Documentation
|
|
125
65
|
|
|
126
|
-
Read
|
|
127
|
-
1. **[docs/README.md](docs/README.md)** — Overview + capabilities
|
|
128
|
-
2. **[docs/project-structure.md](docs/project-structure.md)** — Where files live
|
|
129
|
-
3. **[docs/patterns.md](docs/patterns.md)** — How to write pages, fetch data, style components
|
|
66
|
+
Read order for V0 / AI agents:
|
|
130
67
|
|
|
131
|
-
|
|
68
|
+
1. `docs/README.md` — Quick import reference
|
|
69
|
+
2. `docs/types.md` — All domain type shapes
|
|
70
|
+
3. `docs/commerce-api.md` — All `commerce.*` method signatures
|
|
71
|
+
4. `docs/patterns.md` — Code templates (pages, components, styling)
|
|
72
|
+
5. `docs/rules.md` — Non-negotiable constraints
|
|
73
|
+
6. `docs/project-structure.md` — Folder map + file ownership
|
|
132
74
|
|
|
133
|
-
|
|
134
|
-
- Frozen architecture files (do not modify)
|
|
135
|
-
- Type shapes for all domain objects
|
|
136
|
-
- Method signatures for all `commerce.*` calls
|
|
137
|
-
- Pre-commit checklist
|
|
75
|
+
## Tech Stack
|
|
138
76
|
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
5. [docs/patterns.md](docs/patterns.md) — Server/client, fetch patterns
|
|
145
|
-
6. [docs/rules.md](docs/rules.md) — Non-negotiable constraints
|
|
77
|
+
- Next.js 16 (App Router)
|
|
78
|
+
- React 19
|
|
79
|
+
- TypeScript (strict)
|
|
80
|
+
- Tailwind CSS 4
|
|
81
|
+
- shadcn/ui (installed per-project via CLI)
|
|
146
82
|
|
|
147
83
|
## Deployment
|
|
148
84
|
|
|
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.
|
|
85
|
+
**Vercel:** Connect repo → set env vars → deploy.
|
|
86
|
+
**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)
|