@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.
Files changed (47) hide show
  1. package/README.md +31 -68
  2. package/dist/index.js +158 -629
  3. package/package.json +1 -1
  4. package/templates/default/.agents/AGENTS.md +27 -0
  5. package/templates/default/.env.example +12 -33
  6. package/templates/default/.eslintrc.json +20 -27
  7. package/templates/default/README.md +60 -119
  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 +45 -113
  17. package/templates/default/components/providers/app-providers.tsx +19 -68
  18. package/templates/default/components/providers/cart-provider.tsx +155 -0
  19. package/templates/default/components/providers/commerce-provider.tsx +34 -0
  20. package/templates/default/components/providers/region-provider.tsx +115 -0
  21. package/templates/default/docs/README.md +52 -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 +44 -42
  26. package/templates/default/docs/types.md +105 -1024
  27. package/templates/default/lib/commerce.ts +52 -135
  28. package/templates/default/lib/env.ts +68 -94
  29. package/templates/default/lib/utils.ts +18 -0
  30. package/templates/default/next.config.ts +7 -0
  31. package/templates/default/package.json +2 -8
  32. package/templates/default/registry.json +6 -0
  33. package/templates/default/styles/tokens.css +81 -0
  34. package/templates/default/components/providers/navigation-provider.tsx +0 -37
  35. package/templates/default/config/site.config.ts +0 -156
  36. package/templates/default/docs/components.md +0 -282
  37. package/templates/default/docs/dependencies.md +0 -61
  38. package/templates/default/lib/auth-context.tsx +0 -213
  39. package/templates/default/lib/cart-provider.tsx +0 -53
  40. package/templates/default/lib/commerce-provider.tsx +0 -48
  41. package/templates/default/lib/region-detection.ts +0 -73
  42. package/templates/default/lib/region-provider.tsx +0 -53
  43. package/templates/default/lib/regions-config.ts +0 -48
  44. package/templates/default/lib/storefront-config.ts +0 -54
  45. package/templates/default/next.config.mjs +0 -51
  46. package/templates/default/proxy.ts +0 -155
  47. package/templates/default/scripts/generate-regions-config.ts +0 -498
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  title: "Patterns (Code Templates)"
3
- purpose: "Canonical code templates for common patterns like server pages, client components, and commerce data fetching"
4
- lastReviewed: "2026-04-29"
3
+ purpose: "Canonical code templates for V0-native Thor Commerce starters"
4
+ lastReviewed: "2026-05-01"
5
5
  ---
6
6
 
7
7
  # Patterns (Code Templates)
@@ -10,122 +10,183 @@ lastReviewed: "2026-04-29"
10
10
 
11
11
  ```tsx
12
12
  // app/products/page.tsx
13
- import { backendCircuitBreaker } from '@thorprovider/adapters';
14
13
  import { commerce } from '@/lib/commerce';
14
+ import type { Product } from '@thorprovider/types';
15
+ import { ProductGrid } from '@/components/product-grid';
15
16
 
16
17
  export default async function ProductsPage() {
17
- const products = await backendCircuitBreaker.execute(
18
- () => commerce.getProducts({ first: 20 }),
19
- [] // shown if backend unreachable
20
- );
18
+ const products: Product[] = await commerce.getProducts({ first: 20 });
21
19
  return <ProductGrid products={products} />;
22
20
  }
23
21
  ```
24
22
 
25
- ❌ Never fetch in client with `useEffect` → causes visible loading flash + worse LCP.
23
+ - Server Components fetch data directly — no useEffect, no loading spinners for initial data.
24
+ - Retry logic is built into the adapter — no manual wrapping needed.
26
25
 
27
26
  ---
28
27
 
29
- ## 2. Client Component
28
+ ## 2. Client Component (Product Card)
30
29
 
31
30
  ```tsx
32
31
  // components/product-card.tsx
33
32
  'use client';
34
- import { useNavigation } from '@thorprovider/providers';
35
- import { Button, Card } from '@thorprovider/components';
33
+ import Link from 'next/link';
34
+ import Image from 'next/image';
36
35
  import type { Product } from '@thorprovider/types';
36
+ import { formatPrice } from '@/lib/utils';
37
37
 
38
38
  export function ProductCard({ product }: { product: Product }) {
39
- const { Link, Image } = useNavigation();
40
39
  return (
41
- <Card>
42
- <Link href={`/products/${product.handle}`}>
43
- <Image src={product.featuredImage?.url ?? ''} alt={product.featuredImage?.altText ?? product.title} width={300} height={300} />
44
- <p>{product.title}</p>
45
- </Link>
46
- <Button>Add to cart</Button>
47
- </Card>
40
+ <Link href={`/products/${product.handle}`} className="group">
41
+ <div className="overflow-hidden rounded-lg">
42
+ <Image
43
+ src={product.featuredImage?.url ?? ''}
44
+ alt={product.featuredImage?.altText ?? product.title}
45
+ width={300}
46
+ height={300}
47
+ className="transition-transform group-hover:scale-105"
48
+ />
49
+ </div>
50
+ <h3 className="mt-2 text-sm font-medium text-foreground">{product.title}</h3>
51
+ <p className="text-sm text-muted-foreground">
52
+ {formatPrice(product.priceRange.minVariantPrice)}
53
+ </p>
54
+ </Link>
48
55
  );
49
56
  }
50
57
  ```
51
58
 
52
- ❌ Never `import Link from 'next/link'` inside `components/` — use `useNavigation()`.
59
+ - Use `next/link` and `next/image` directly.
60
+ - Use `product.handle` in URLs (not `product.id`).
61
+ - Use `product.featuredImage?.url` (not `.thumbnail`).
62
+ - Always `formatPrice(money)` — never render `money.amount` directly.
53
63
 
54
64
  ---
55
65
 
56
- ## 3. Styling
66
+ ## 3. Cart Operations
57
67
 
58
68
  ```tsx
59
- // ✅ CSS tokens (dark mode + theming work automatically)
60
- <div style={{ color: 'var(--foreground)', background: 'var(--background)' }} />
61
- <button className="bg-[var(--primary-9)] hover:bg-[var(--primary-8)]" />
69
+ // components/add-to-cart-button.tsx
70
+ 'use client';
71
+ import { useCart } from '@/components/providers/cart-provider';
72
+ import { Button } from '@/components/ui/button';
62
73
 
63
- // ❌ Hardcoded colors (breaks dark mode)
64
- <div style={{ color: '#1a1a1a', background: '#ffffff' }} />
65
- <button className="bg-blue-500 hover:bg-blue-600" />
74
+ export function AddToCartButton({ variantId }: { variantId: string }) {
75
+ const { addItem, isLoading } = useCart();
76
+
77
+ return (
78
+ <Button
79
+ onClick={() => addItem(variantId, 1)}
80
+ disabled={isLoading}
81
+ >
82
+ {isLoading ? 'Adding...' : 'Add to Cart'}
83
+ </Button>
84
+ );
85
+ }
66
86
  ```
67
87
 
68
- **Available tokens:** `--background`, `--foreground`, `--border`, `--primary-9/8`, `--success`, `--warning`, `--error`
88
+ - Import `useCart` from `@/components/providers/cart-provider`.
89
+ - Cart methods: `addItem(variantId, quantity)`, `removeItem(lineItemId)`, `updateQuantity(lineItemId, qty)`, `clearCart()`.
69
90
 
70
91
  ---
71
92
 
72
- ## 4. API Route (GET)
93
+ ## 4. Region/Currency
73
94
 
74
- ```ts
75
- // app/api/products/route.ts
76
- import { backendCircuitBreaker } from '@thorprovider/adapters';
77
- import { commerce } from '@/lib/commerce';
95
+ ```tsx
96
+ // components/currency-selector.tsx
97
+ 'use client';
98
+ import { useRegion } from '@/components/providers/region-provider';
99
+
100
+ export function CurrencySelector() {
101
+ const { region, regions, setRegion, currencyCode } = useRegion();
78
102
 
79
- export async function GET() {
80
- try {
81
- const products = await backendCircuitBreaker.execute(
82
- () => commerce.getProducts(),
83
- []
84
- );
85
- return Response.json(products);
86
- } catch {
87
- return Response.json({ error: 'Service unavailable' }, { status: 503 });
88
- }
103
+ return (
104
+ <select
105
+ value={region?.id ?? ''}
106
+ onChange={(e) => setRegion(e.target.value)}
107
+ >
108
+ {regions.map((r) => (
109
+ <option key={r.id} value={r.id}>{r.name} ({r.currency})</option>
110
+ ))}
111
+ </select>
112
+ );
89
113
  }
90
114
  ```
91
115
 
116
+ - Import `useRegion` from `@/components/providers/region-provider`.
117
+
118
+ ---
119
+
120
+ ## 5. Styling (CSS Tokens)
121
+
122
+ ```tsx
123
+ // CSS tokens (dark mode + theming work automatically)
124
+ <div className="bg-background text-foreground border-border" />
125
+ <button className="bg-primary text-primary-foreground hover:bg-primary/90" />
126
+ <p className="text-muted-foreground" />
127
+
128
+ // Hardcoded colors (breaks dark mode)
129
+ <div style={{ color: '#1a1a1a', background: '#ffffff' }} />
130
+ ```
131
+
132
+ **Available tokens:** `--background`, `--foreground`, `--border`, `--primary`, `--secondary`, `--muted`, `--accent`, `--destructive` (+ `-foreground` variants)
133
+
92
134
  ---
93
135
 
94
- ## 5. Storefront Config (Theme Accent)
136
+ ## 6. Price Display
95
137
 
96
- `lib/storefront-config.ts` is called automatically in `app/layout.tsx` to apply a backend-driven accent color override. You can also read it in any server component:
138
+ ```tsx
139
+ import { formatPrice } from '@/lib/utils';
140
+ import type { Money } from '@thorprovider/types';
97
141
 
98
- ```ts
99
- // app/some-page/page.tsx
100
- import { getStorefrontConfig } from '@/lib/storefront-config';
142
+ // Correct
143
+ <span>{formatPrice(variant.price)}</span>
144
+ <span>{formatPrice(product.priceRange.minVariantPrice)}</span>
101
145
 
102
- export default async function SomePage() {
103
- const config = await getStorefrontConfig(); // null if backend unreachable or not configured
104
- const accentColor = config?.themeAccentColor; // e.g. "indigo", "blue", or custom oklch value
105
- // ...
106
- }
146
+ // Wrong — Money.amount is a string, not displayable directly
147
+ <span>${variant.price.amount}</span>
148
+ <span>{variant.prices[0].amount}</span> // prices[] doesn't exist!
107
149
  ```
108
150
 
109
- - Returns `null` gracefully when the backend is unreachable or the provider does not implement `getStorefrontConfig`.
110
- - Result is cached per React server request (deduped across components in the same render).
151
+ **Key facts about Money:**
152
+ - `Money.amount` is a **decimal string** (`"29.99"`) — NOT cents, NOT a number
153
+ - `ProductVariant.price` is a **single Money object** — NOT an array
154
+ - Always use `formatPrice()` for locale-aware currency formatting
111
155
 
112
156
  ---
113
157
 
114
- ## 6. Webhook ISR Revalidation
158
+ ## 7. Authentication
159
+
160
+ ```tsx
161
+ 'use client';
162
+ import { commerce } from '@/lib/commerce';
115
163
 
116
- The app ships with a webhook endpoint at `app/api/revalidate/route.ts`. Enable it by setting `FRONTEND_WEBHOOK_SECRET` in `.env`:
164
+ // Auth is built into the adapter — call commerce.auth.* directly
165
+ async function handleLogin(email: string, password: string) {
166
+ const { customer } = await commerce.auth.login({ email, password });
167
+ // Redirect on success
168
+ }
117
169
 
118
- ```bash
119
- FRONTEND_WEBHOOK_SECRET=your-shared-secret
170
+ // Check auth state
171
+ const isAuth = await commerce.auth.isAuthenticated();
172
+ const customer = await commerce.auth.getCurrentCustomer();
120
173
  ```
121
174
 
122
- The backend plugin sends `POST /api/revalidate` with `x-webhook-secret` header. Supported events:
175
+ - Auth is part of `@thorprovider/adapters` — no separate provider needed.
176
+ - See `docs/commerce-api.md` for full auth API reference.
123
177
 
124
- | Event | Effect |
125
- |-------|--------|
126
- | `site_config.updated` | Revalidates `site-config` cache tag |
127
- | `storefront_config.updated` | Revalidates `storefront-config` cache tag |
128
- | `sales_channel.updated` | Revalidates both tags |
129
- | _(any other)_ | Revalidates both tags as a safety net |
178
+ ---
130
179
 
131
- ❌ Never expose `FRONTEND_WEBHOOK_SECRET` in client-side code — it is a server-only env var.
180
+ ## Import Path Summary
181
+
182
+ | What | Import From |
183
+ |------|-------------|
184
+ | Types | `@thorprovider/types` |
185
+ | Commerce data | `@/lib/commerce` |
186
+ | Cart hook | `@/components/providers/cart-provider` |
187
+ | Region hook | `@/components/providers/region-provider` |
188
+ | Commerce hook | `@/components/providers/commerce-provider` |
189
+ | Utilities | `@/lib/utils` (cn, formatPrice) |
190
+ | UI components | `@/components/ui/*` (shadcn/ui) |
191
+ | Navigation | `next/link` |
192
+ | Images | `next/image` |
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  title: "Project Structure"
3
- purpose: "Folder map and file ownership reference for generated Thor Commerce storefronts"
4
- lastReviewed: "2026-04-29"
3
+ purpose: "Folder map and file ownership for V0-native Thor Commerce template"
4
+ lastReviewed: "2026-05-01"
5
5
  ---
6
6
 
7
7
  # Project Structure
@@ -9,41 +9,43 @@ lastReviewed: "2026-04-29"
9
9
  ## Folder Map
10
10
 
11
11
  ```
12
+ .agents/
13
+ AGENTS.md ← V0 context (≤998 chars, Layer 1 injection)
14
+
15
+ styles/
16
+ tokens.css ← Design tokens (swap for client rebrand)
17
+
12
18
  app/
13
- layout.tsx ← Root layout: ThemeProvider + AppProviders + IP region detection (frozen)
14
- page.tsx ← Placeholder home page (replace with your content)
15
- error.tsx ← Error boundary for provider/route failures
16
- global-error.tsx ← Global error boundary (catches root layout crashes, env var errors)
17
- not-found.tsx ← 404 page
18
- globals.css ← Global styles
19
- products/ ← Add your feature pages here
19
+ layout.tsx ← Root layout: AppProviders wrapper (frozen)
20
+ page.tsx ← Home page placeholder (V0 replaces)
21
+ error.tsx ← Error boundary
22
+ global-error.tsx ← Root error boundary (layout crashes)
23
+ not-found.tsx ← 404 page
24
+ globals.css ← Imports tokens.css + Tailwind base
20
25
  api/
21
- revalidate/
22
- route.ts ← Webhook ISR revalidation endpoint (opt-in)
26
+ revalidate/route.ts ← Webhook ISR revalidation (opt-in)
23
27
  backend-unavailable/
24
- page.tsx ← Shown by proxy.ts when backend is unreachable
28
+ page.tsx ← Shown when backend is unreachable
25
29
 
26
- components/ ← Your page-specific components
30
+ components/
27
31
  providers/
28
- app-providers.tsx ← Provider chain composite (frozen — never reorder)
29
- navigation-provider.tsx ← ClientNavigationProvider wrapper
30
-
31
- config/
32
- site.config.ts ← Brand: name, logo, navigation, color preset
33
-
34
- lib/ ← Infrastructure (frozen — do not modify unless adding utilities)
35
- commerce.ts ← Commerce singleton (createProvider, lazy proxy) — FROZEN
36
- commerce-provider.tsx ← ClientCommerceProvider + useCommerce hook — FROZEN
37
- region-provider.tsx ← ClientRegionProvider + useRegion hook — FROZEN
38
- auth-context.tsx ← AuthProvider + useAuth hook — FROZEN
39
- cart-provider.tsx ← ClientCartProvider + useCart hook — FROZEN
40
- storefront-config.ts ← Backend-driven storefront config fetch (theme accent, cached) — FROZEN
41
- region-detection.ts ← IP-based region detection from Vercel/Cloudflare headers — FROZEN
42
- regions-config.ts ← Auto-generated locale→region map — DO NOT EDIT (overwritten on build)
43
- env.ts ← Zod-validated environment variable schema — FROZEN
44
- utils.ts ← cn() class merging helper
45
-
46
- proxy.ts ← Next.js edge middleware: detects backend unavailability, redirects to /backend-unavailable
32
+ app-providers.tsx ← Provider chain: Commerce > Region > Cart (frozen)
33
+ commerce-provider.tsx ← CommerceProvider + useCommerce hook
34
+ region-provider.tsx ← RegionProvider + useRegion hook
35
+ cart-provider.tsx ← CartProvider + useCart hook
36
+ ui/ ← shadcn/ui components (npx shadcn@latest add)
37
+ [feature].tsx ← Page-specific components (V0 generates)
38
+
39
+ lib/
40
+ commerce.ts ← Commerce singleton — FROZEN
41
+ env.ts ← Zod environment schema — FROZEN
42
+ utils.ts ← cn() + formatPrice()
43
+
44
+ docs/
45
+ types.md ← Full @thorprovider/types reference
46
+ patterns.md ← Code examples and patterns
47
+ commerce-api.md ← All commerce.* method signatures
48
+ rules.md ← Non-negotiable constraints
47
49
  ```
48
50
 
49
51
  ## Where Does X Go?
@@ -52,28 +54,34 @@ proxy.ts ← Next.js edge middleware: detects backend unavaila
52
54
  |------|----------|
53
55
  | New page | `app/[slug]/page.tsx` |
54
56
  | Page-specific component | `components/[feature].tsx` |
55
- | Reusable UI primitive | `@thorprovider/components` first (see `dependencies.md`) |
56
- | Site name, logo, nav links | `config/site.config.ts` |
57
+ | Reusable UI primitive | `npx shadcn@latest add [component]` → `components/ui/` |
57
58
  | API route | `app/api/[route]/route.ts` |
58
- | Environment variables | `.env` (copy from `.env.example`) |
59
+ | Environment variables | `.env.local` |
59
60
 
60
61
  ## Component Decision
61
62
 
62
63
  ```
63
- Need a UI component?
64
- ├─ Exists in @thorprovider/components? → import { X } from '@thorprovider/components'
65
- └─ Not found? → create in components/[feature].tsx
66
- (compose using @thorprovider/components inside)
67
- ```
68
-
69
- → See `dependencies.md` for full `@thorprovider/components` inventory.
70
-
71
- ## Auto-Generated Files
72
-
73
- `lib/regions-config.ts` is generated automatically on `dev` and `build` via the `predev`/`prebuild` scripts.
74
-
75
- ```bash
76
- yarn generate:regions # regenerate manually
64
+ Need a UI element?
65
+ ├─ Standard primitive (button, card, dialog)?
66
+ │ → npx shadcn@latest add [component]
67
+ │ → import from '@/components/ui/[component]'
68
+ │
69
+ ├─ Commerce-specific (product card, cart drawer)?
70
+ │ → V0 generates it custom for this project
71
+ │ → Place in components/[feature].tsx
72
+ │
73
+ └─ Page layout?
74
+ → Use Tailwind CSS directly in the page
77
75
  ```
78
76
 
79
- **Never edit `lib/regions-config.ts` by hand** — it will be overwritten on the next build.
77
+ ## File Ownership
78
+
79
+ | File | Owner | V0 Modifies? |
80
+ |------|-------|--------------|
81
+ | `lib/commerce.ts` | Infrastructure | Never |
82
+ | `lib/env.ts` | Infrastructure | Never |
83
+ | `components/providers/*` | Infrastructure | Never |
84
+ | `styles/tokens.css` | Brand config | Only via create-thor-app flags |
85
+ | `app/globals.css` | Design tokens | Only to add custom tokens |
86
+ | `app/**/*.tsx` | Feature code | Yes — V0 creates pages |
87
+ | `components/**/*.tsx` | Feature code | Yes — V0 creates components |
@@ -1,64 +1,66 @@
1
1
  ---
2
2
  title: "Rules"
3
- purpose: "Non-negotiable constraints that protect backend swappability, dark mode, and framework portability"
4
- lastReviewed: "2026-04-29"
3
+ purpose: "Non-negotiable constraints for V0-native Thor Commerce starters"
4
+ lastReviewed: "2026-05-01"
5
5
  ---
6
6
 
7
7
  # Rules
8
8
 
9
- These rules protect the app's ability to: swap backends without code changes, work in dark mode, survive backend downtime, and stay framework-portable.
9
+ Non-negotiable constraints. Breaking these causes build failures, runtime crashes, or backend lock-in.
10
10
 
11
- ## Non-Negotiables
11
+ ## Critical Rules
12
12
 
13
- | Rule | Why | Consequence if broken |
14
- |------|-----|-----------------------|
15
- | No backend SDK imports (e.g. `@medusajs/js-sdk`, `@shopify/api`) | Backend is swappable via adapters | Vendor lock-in; migration requires rewrite |
16
- | No raw `fetch(COMMERCE_API_URL + '...')` | Raw URLs bypass the adapter layer | No retry, credential leak, lock-in |
17
- | No `import Link from 'next/link'` in `components/` | Components must be framework-portable | Breaks portability; use `useNavigation()` |
18
- | Wrap reads in `backendCircuitBreaker.execute(fn, fallback)` | Backend can be intermittently unavailable | Page crashes instead of showing fallback |
19
- | No `#hex` / `rgb()` inline colors | CSS tokens enable dark mode + theming | Dark mode breaks; theme non-customizable |
20
- | Don't re-implement `@thorprovider/components` components | 55 exist with full TypeScript + accessibility | Duplicate code, inconsistent UI — see `dependencies.md` for full list |
13
+ | Rule | Why | Consequence |
14
+ |------|-----|-------------|
15
+ | Import types from `@thorprovider/types` | Single source of truth for all domain objects | Type drift, adapter incompatibility |
16
+ | Never import `@thorprovider/components` | Doesn't exist in this template | Build failure |
17
+ | Never import `@thorprovider/providers` | Providers are local code in `components/providers/` | Build failure |
18
+ | Never import backend SDKs (`@medusajs/*`, `@shopify/*`) | Backend is swappable via adapters | Vendor lock-in |
19
+ | Never raw `fetch(COMMERCE_API_URL + '...')` | Bypasses adapter layer | No retry, no credential safety |
20
+ | Always `formatPrice(money)` | `Money.amount` is a string like "29.99" | Broken display |
21
+ | Use `product.handle` in URLs | Handles are URL-safe slugs | Broken SEO |
22
+ | Use `product.featuredImage?.url` | Not `.thumbnail` — that doesn't exist | Undefined error |
23
+ | `variant.price` is singular Money | Not `prices[]` — that doesn't exist | Type error |
24
+ | No hardcoded `#hex` / `rgb()` colors | CSS tokens enable dark mode + theming | Dark mode breaks |
25
+ | Use `next/link` for navigation | V0 is trained on Next.js primitives | Unnecessary abstraction |
26
+ | Use `next/image` for images | Optimized by default | Missing optimization |
27
+ | Do not fork UI into mock-vs-live implementations | Runtime already switches providers underneath the same interface | Drift, duplicated logic |
21
28
 
22
29
  ## Provider Chain (Frozen Order)
23
30
 
24
- Root layout (`app/layout.tsx`) wraps the full tree with `ThemeProvider`, then delegates to `AppProviders`:
31
+ **File:** `components/providers/app-providers.tsx`
25
32
 
26
33
  ```tsx
27
- // app/layout.tsx
28
- <ThemeProvider preset={siteConfig.preset}>
29
- <AppProviders initialRegionId={initialRegionId}>
30
- {children}
31
- </AppProviders>
32
- </ThemeProvider>
34
+ <CommerceProvider>
35
+ <RegionProvider>
36
+ <CartProvider>
37
+ {children}
38
+ </CartProvider>
39
+ </RegionProvider>
40
+ </CommerceProvider>
33
41
  ```
34
42
 
35
- **File:** `components/providers/app-providers.tsx`
43
+ CartProvider and RegionProvider depend on commerce. Reordering = runtime crash.
44
+ To add a provider → wrap `{children}` **inside** `CartProvider`.
36
45
 
37
- ```tsx
38
- <ClientCommerceProvider>
39
- <ClientRegionProvider initialRegionId={initialRegionId}>
40
- <AuthProvider>
41
- <ClientCartProvider>
42
- <ClientNavigationProvider>
43
- {children}
44
- </ClientNavigationProvider>
45
- </ClientCartProvider>
46
- </AuthProvider>
47
- </ClientRegionProvider>
48
- </ClientCommerceProvider>
49
- ```
46
+ ## Frozen Files
47
+
48
+ Never modify these — they are infrastructure:
50
49
 
51
- Each provider depends on the context of the prior one. Reordering = runtime crash.
52
- To add a custom provider → wrap `{children}` **inside** `ClientNavigationProvider`.
50
+ | File | Purpose |
51
+ |------|---------|
52
+ | `lib/commerce.ts` | Commerce singleton (createProvider + lazy proxy) |
53
+ | `lib/env.ts` | Zod-validated environment schema |
54
+ | `components/providers/app-providers.tsx` | Provider chain composite |
53
55
 
54
56
  ## Pre-Commit Checklist
55
57
 
56
- - [ ] Checked `@thorprovider/components` inventory before creating a new UI component?
57
- - [ ] All `commerce.get*()` reads wrapped in `backendCircuitBreaker.execute(fn, fallback)`?
58
- - [ ] No backend SDK imports (`@medusajs/js-sdk`, `@shopify/api`, etc.)?
58
+ - [ ] No `@thorprovider/components` or `@thorprovider/providers` imports?
59
+ - [ ] No backend SDK imports (`@medusajs/*`, `@shopify/*`)?
59
60
  - [ ] No raw `fetch(COMMERCE_API_URL...)` calls?
60
- - [ ] No `import Link/Image from 'next/*'` inside `components/`?
61
- - [ ] No hardcoded `#hex`, `rgb()`, or Tailwind arbitrary non-token colors?
62
- - [ ] `yarn type-check` passes?
61
+ - [ ] All prices rendered via `formatPrice()`?
62
+ - [ ] Using `product.handle` in URLs?
63
+ - [ ] No hardcoded hex/rgb colors?
64
+ - [ ] Types from `@thorprovider/types` (not redefined locally)?
65
+ - [ ] `tsc --noEmit` passes?
63
66
  - [ ] Server components fetch; client components receive data via props?
64
- - [ ] Provider chain order unchanged?