@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
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: "Patterns (Code Templates)"
|
|
3
|
-
purpose: "Canonical code templates for
|
|
4
|
-
lastReviewed: "2026-
|
|
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
|
|
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
|
-
|
|
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
|
|
35
|
-
import
|
|
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
|
-
<
|
|
42
|
-
<
|
|
43
|
-
<Image
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
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
|
-
|
|
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.
|
|
66
|
+
## 3. Cart Operations
|
|
57
67
|
|
|
58
68
|
```tsx
|
|
59
|
-
//
|
|
60
|
-
|
|
61
|
-
|
|
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
|
-
|
|
64
|
-
|
|
65
|
-
|
|
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
|
-
|
|
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.
|
|
93
|
+
## 4. Region/Currency
|
|
73
94
|
|
|
74
|
-
```
|
|
75
|
-
//
|
|
76
|
-
|
|
77
|
-
import {
|
|
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
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
() =>
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
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
|
-
##
|
|
136
|
+
## 6. Price Display
|
|
95
137
|
|
|
96
|
-
|
|
138
|
+
```tsx
|
|
139
|
+
import { formatPrice } from '@/lib/utils';
|
|
140
|
+
import type { Money } from '@thorprovider/types';
|
|
97
141
|
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
142
|
+
// Correct
|
|
143
|
+
<span>{formatPrice(variant.price)}</span>
|
|
144
|
+
<span>{formatPrice(product.priceRange.minVariantPrice)}</span>
|
|
101
145
|
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
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
|
-
|
|
110
|
-
-
|
|
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
|
-
##
|
|
158
|
+
## 7. Authentication
|
|
159
|
+
|
|
160
|
+
```tsx
|
|
161
|
+
'use client';
|
|
162
|
+
import { commerce } from '@/lib/commerce';
|
|
115
163
|
|
|
116
|
-
|
|
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
|
-
|
|
119
|
-
|
|
170
|
+
// Check auth state
|
|
171
|
+
const isAuth = await commerce.auth.isAuthenticated();
|
|
172
|
+
const customer = await commerce.auth.getCurrentCustomer();
|
|
120
173
|
```
|
|
121
174
|
|
|
122
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
4
|
-
lastReviewed: "2026-
|
|
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
|
|
14
|
-
page.tsx
|
|
15
|
-
error.tsx
|
|
16
|
-
global-error.tsx
|
|
17
|
-
not-found.tsx
|
|
18
|
-
globals.css
|
|
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
|
|
28
|
+
page.tsx ← Shown when backend is unreachable
|
|
25
29
|
|
|
26
|
-
components/
|
|
30
|
+
components/
|
|
27
31
|
providers/
|
|
28
|
-
app-providers.tsx
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
commerce
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
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 |
|
|
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
|
|
59
|
+
| Environment variables | `.env.local` |
|
|
59
60
|
|
|
60
61
|
## Component Decision
|
|
61
62
|
|
|
62
63
|
```
|
|
63
|
-
Need a UI
|
|
64
|
-
├─
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
→
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
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
|
-
|
|
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
|
|
4
|
-
lastReviewed: "2026-
|
|
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
|
-
|
|
9
|
+
Non-negotiable constraints. Breaking these causes build failures, runtime crashes, or backend lock-in.
|
|
10
10
|
|
|
11
|
-
##
|
|
11
|
+
## Critical Rules
|
|
12
12
|
|
|
13
|
-
| Rule | Why | Consequence
|
|
14
|
-
|
|
15
|
-
|
|
|
16
|
-
|
|
|
17
|
-
|
|
|
18
|
-
|
|
|
19
|
-
|
|
|
20
|
-
|
|
|
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
|
-
|
|
31
|
+
**File:** `components/providers/app-providers.tsx`
|
|
25
32
|
|
|
26
33
|
```tsx
|
|
27
|
-
|
|
28
|
-
<
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
</
|
|
34
|
+
<CommerceProvider>
|
|
35
|
+
<RegionProvider>
|
|
36
|
+
<CartProvider>
|
|
37
|
+
{children}
|
|
38
|
+
</CartProvider>
|
|
39
|
+
</RegionProvider>
|
|
40
|
+
</CommerceProvider>
|
|
33
41
|
```
|
|
34
42
|
|
|
35
|
-
|
|
43
|
+
CartProvider and RegionProvider depend on commerce. Reordering = runtime crash.
|
|
44
|
+
To add a provider → wrap `{children}` **inside** `CartProvider`.
|
|
36
45
|
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
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
|
-
|
|
52
|
-
|
|
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
|
-
- [ ]
|
|
57
|
-
- [ ]
|
|
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
|
-
- [ ]
|
|
61
|
-
- [ ]
|
|
62
|
-
- [ ]
|
|
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?
|