@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.
Files changed (48) hide show
  1. package/README.md +6 -55
  2. package/dist/index.js +154 -626
  3. package/package.json +2 -2
  4. package/templates/default/.agents/AGENTS.md +27 -0
  5. package/templates/default/.env.example +8 -30
  6. package/templates/default/.eslintrc.json +20 -27
  7. package/templates/default/README.md +52 -123
  8. package/templates/default/ai-validator.json +47 -29
  9. package/templates/default/app/api/revalidate/route.ts +27 -36
  10. package/templates/default/app/backend-unavailable/page.tsx +3 -7
  11. package/templates/default/app/error.tsx +1 -2
  12. package/templates/default/app/global-error.tsx +3 -3
  13. package/templates/default/app/globals.css +1 -71
  14. package/templates/default/app/layout.tsx +16 -38
  15. package/templates/default/app/not-found.tsx +1 -1
  16. package/templates/default/app/page.tsx +10 -119
  17. package/templates/default/components/providers/app-providers.tsx +19 -68
  18. package/templates/default/components/providers/cart-provider.tsx +143 -0
  19. package/templates/default/components/providers/commerce-provider.tsx +33 -0
  20. package/templates/default/components/providers/region-provider.tsx +105 -0
  21. package/templates/default/docs/README.md +46 -37
  22. package/templates/default/docs/commerce-api.md +58 -125
  23. package/templates/default/docs/patterns.md +128 -67
  24. package/templates/default/docs/project-structure.md +58 -50
  25. package/templates/default/docs/rules.md +43 -42
  26. package/templates/default/docs/types.md +105 -1024
  27. package/templates/default/lib/commerce.ts +33 -132
  28. package/templates/default/lib/env.ts +24 -94
  29. package/templates/default/lib/utils.ts +18 -0
  30. package/templates/default/next-env.d.ts +1 -1
  31. package/templates/default/next.config.ts +7 -0
  32. package/templates/default/package.json +2 -8
  33. package/templates/default/registry.json +6 -0
  34. package/templates/default/styles/tokens.css +81 -0
  35. package/templates/default/components/providers/navigation-provider.tsx +0 -37
  36. package/templates/default/config/site.config.ts +0 -156
  37. package/templates/default/docs/components.md +0 -282
  38. package/templates/default/docs/dependencies.md +0 -61
  39. package/templates/default/lib/auth-context.tsx +0 -213
  40. package/templates/default/lib/cart-provider.tsx +0 -53
  41. package/templates/default/lib/commerce-provider.tsx +0 -48
  42. package/templates/default/lib/region-detection.ts +0 -73
  43. package/templates/default/lib/region-provider.tsx +0 -53
  44. package/templates/default/lib/regions-config.ts +0 -48
  45. package/templates/default/lib/storefront-config.ts +0 -54
  46. package/templates/default/next.config.mjs +0 -51
  47. package/templates/default/proxy.ts +0 -155
  48. 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": "3.1.3",
4
- "description": "CLI to scaffold a new Thor Commerce application from @thorprovider/core template",
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 Core Template — Environment Configuration
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
- # Your commerce backend API URL (e.g., Medusa, Shopify, custom provider)
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 — Thor Commerce plugin)
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
- // FROZEN: Prevent L3 components from importing directly from 'next/'
5
- // Instead, they must use abstractions from @thorprovider/providers (useNavigation, useImage, etc.)
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": ["next/link", "next/image", "next/router"],
12
- "message": "L3 components must use useNavigation() from @thorprovider/providers instead of importing next/link directly. This maintains abstraction layers and allows V0 to generate provider-agnostic code.",
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": ["next/*"],
17
- "importNames": ["default"],
18
- "message": "L3 components should avoid importing from 'next/' directly. Use abstractions from @thorprovider/providers instead.",
19
- "allowTransitive": true
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
- // FROZEN: Prevent hardcoded colors (require CSS variables instead)
26
- "@typescript-eslint/no-unused-expressions": "off",
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: Core Package
3
- purpose: Documentation for @thorprovider/core storefront template
4
- description: Next.js storefront template with headless commerce
2
+ title: "@thorprovider/core"
3
+ purpose: "V0-native storefront template for Thor Commerce Builder"
4
+ lastReviewed: "2026-05-01"
5
5
  ---
6
6
 
7
- # [App Name]
7
+ # @thorprovider/core v2.0.0
8
8
 
9
- Next.js 16 storefront with headless commerce. Commerce, auth, i18n, and theming are pre-configured via `@thorprovider/*` packages — just connect your backend and build features.
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
- ## 🚀 Development Workflow
13
+ **2 npm dependencies** — everything else is local code V0 can read:
14
14
 
15
- ### Step 1: Create the App (Local)
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
- ```bash
18
- # Minimal
19
- yarn create:app --name my-store
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
- This command:
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
- ### Step 2: Connect to GitHub
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
- 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_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
- Now, create a product filter sidebar for the /products page that filters by category and price range.
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
- ## 🔒 Frozen Files (Do NOT Modify)
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
- These files define the app's architecture and are **frozen by design**. V0 respects these; you must too:
46
+ ## Frozen Files (Do NOT Modify)
93
47
 
94
48
  | File | Purpose |
95
49
  |------|---------|
96
- | `lib/commerce.ts` | Commerce provider initialization (singleton) |
97
- | `lib/commerce-provider.tsx` | CommerceProvider context wrapper |
98
- | `lib/region-provider.tsx` | RegionProvider context wrapper |
99
- | `lib/auth-context.tsx` | Authentication context |
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
- - Regional commerce (IP-based region detection via Vercel/Cloudflare geolocation headers)
115
- - Shopping cart (persistent, backend-synced via `lib/cart-provider.tsx`)
116
- - Authentication (JWT via `lib/auth-context.tsx`)
117
- - Dark mode + CSS token theming + backend-driven accent color override (`lib/storefront-config.ts`)
118
- - Circuit breaker (auto-fallback when backend is unavailable, auto-resets after 60s)
119
- - Webhook ISR revalidation (`app/api/revalidate/route.ts`, opt-in via `FRONTEND_WEBHOOK_SECRET`)
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
- ### For Humans (You)
64
+ ## Documentation
125
65
 
126
- Read in this order:
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
- ### For V0 / AI Agents
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
- **Copy `.v0-context.md` to V0's first message.** It includes:
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
- **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
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 (`NEXT_PUBLIC_COMMERCE_API_URL`, `NODE_AUTH_TOKEN`) → deploy.
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": "1.1.0",
3
- "description": "V0 Stop Hooks validation criteria for Thor Commerce storefront projects",
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-1.5-sm",
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-var-declaration-tsx",
76
+ "id": "no-raw-money-render",
95
77
  "filePattern": "**/*.tsx",
96
- "pattern": "\\bvar\\s+",
97
- "description": "Use const/let instead of var"
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": "no-useeffect-commerce-fetch",
101
- "filePattern": "components/**/*.tsx",
102
- "pattern": "useEffect[\\s\\S]{0,200}commerce\\.|useEffect[\\s\\S]{0,200}fetch\\([^)]*COMMERCE",
103
- "description": "Never fetch commerce data inside useEffect in components — fetch in server components (app/*/page.tsx) and pass data as props. useEffect + commerce fetch causes loading flash and worse LCP."
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 Thor Commerce backend plugin
5
- * and triggers ISR revalidation for the affected pages/tags.
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; sales_channel_id?: string; timestamp?: 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 'site_config.updated':
44
- revalidateTag('site-config', 'max');
45
- break;
46
- case 'storefront_config.updated':
47
- revalidateTag('storefront-config', 'max');
48
- break;
49
- case 'sales_channel.updated':
50
- revalidateTag('site-config', 'max');
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 everything as a safety net
55
- revalidateTag('site-config', 'max');
56
- revalidateTag('storefront-config', 'max');
57
- break;
45
+ // Unknown event — revalidate all commerce data
46
+ revalidateTag('products', 'max')
47
+ revalidateTag('collections', 'max')
48
+ break
58
49
  }
59
50
 
60
- // Also revalidate the root path for any static pages
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 proxy.ts health check detects the commerce backend is unreachable.
5
- * Self-contained — zero dependency on providers or @thorprovider/components because the
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/layout.tsx provider chain
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 — ThemeProvider may have crashed.
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 ThemeProvider (which may be the root cause of the crash).
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 ThemeProvider may have crashed
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)