@thorprovider/create-thor-app 2.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 (42) hide show
  1. package/README.md +470 -0
  2. package/dist/index.js +1054 -0
  3. package/package.json +46 -0
  4. package/templates/default/.env.example +56 -0
  5. package/templates/default/.eslintrc.json +43 -0
  6. package/templates/default/README.md +151 -0
  7. package/templates/default/app/api/revalidate/route.ts +64 -0
  8. package/templates/default/app/backend-unavailable/page.tsx +85 -0
  9. package/templates/default/app/error.tsx +58 -0
  10. package/templates/default/app/global-error.tsx +208 -0
  11. package/templates/default/app/globals.css +125 -0
  12. package/templates/default/app/layout.tsx +50 -0
  13. package/templates/default/app/not-found.tsx +31 -0
  14. package/templates/default/app/page.tsx +124 -0
  15. package/templates/default/components/providers/app-providers.tsx +77 -0
  16. package/templates/default/components/providers/navigation-provider.tsx +37 -0
  17. package/templates/default/config/site.config.ts +156 -0
  18. package/templates/default/docs/README.md +46 -0
  19. package/templates/default/docs/commerce-api.md +243 -0
  20. package/templates/default/docs/components.md +276 -0
  21. package/templates/default/docs/dependencies.md +53 -0
  22. package/templates/default/docs/patterns.md +100 -0
  23. package/templates/default/docs/project-structure.md +53 -0
  24. package/templates/default/docs/rules.md +51 -0
  25. package/templates/default/docs/types.md +329 -0
  26. package/templates/default/lib/auth-context.tsx +213 -0
  27. package/templates/default/lib/cart-provider.tsx +53 -0
  28. package/templates/default/lib/commerce-provider.tsx +48 -0
  29. package/templates/default/lib/commerce.ts +165 -0
  30. package/templates/default/lib/env.ts +147 -0
  31. package/templates/default/lib/region-detection.ts +80 -0
  32. package/templates/default/lib/region-provider.tsx +53 -0
  33. package/templates/default/lib/regions-config.ts +48 -0
  34. package/templates/default/lib/storefront-config.ts +54 -0
  35. package/templates/default/lib/utils.ts +10 -0
  36. package/templates/default/next-env.d.ts +6 -0
  37. package/templates/default/next.config.mjs +51 -0
  38. package/templates/default/package.json +42 -0
  39. package/templates/default/postcss.config.mjs +8 -0
  40. package/templates/default/proxy.ts +155 -0
  41. package/templates/default/scripts/generate-regions-config.ts +498 -0
  42. package/templates/default/tsconfig.json +43 -0
@@ -0,0 +1,276 @@
1
+ # Available @thorprovider/components
2
+
3
+ All components import from `@thorprovider/components`. They are pure React (no Next.js), use semantic CSS tokens, and accept data + callbacks via props.
4
+
5
+ ```tsx
6
+ import { Button, ProductCard, CartItem } from '@thorprovider/components';
7
+ ```
8
+
9
+ ---
10
+
11
+ ## Ecommerce Components
12
+
13
+ These are purpose-built for commerce UIs. Use them instead of building from scratch.
14
+
15
+ | Component | Key Props | Callbacks |
16
+ |-----------|-----------|-----------|
17
+ | `ProductCard` | `title`, `price`, `originalPrice`, `image`, `href` | `onAddToCart` |
18
+ | `ProductImage` | `src`, `alt`, `fallbackSrc`, `aspectRatio` | `onError` |
19
+ | `ProductFilter` | `groups`, `selectedFilters` | `onFilterChange`, `onClearAll` |
20
+ | `ProductQuickView` | `open`, `product` | `onClose`, `onAddToCart` |
21
+ | `VariantSelector` | `label`, `options`, `value` | `onChange` |
22
+ | `PriceDisplay` | `price`, `originalPrice`, `currency` | — |
23
+ | `QuantitySelector` | `value`, `min`, `max` | `onChange` |
24
+ | `WishlistToggle` | `isWishlisted`, `size` | `onToggle` |
25
+ | `CartItem` | `id`, `title`, `quantity`, `price`, `image` | `onQuantityChange`, `onRemove` |
26
+ | `CartSummary` | `subtotal`, `total`, `shipping`, `tax` | `onCheckout` |
27
+ | `CartDrawer` | `open`, `items` | `onOpenChange`, `onQuantityChange`, `onRemove`, `onCheckout` |
28
+ | `CheckoutStepIndicator` | `steps`, `currentStep`, `completedSteps` | `onStepClick` |
29
+ | `SearchInput` | `value`, `placeholder`, `inputSize` | `onChange`, `onClear` |
30
+ | `Rating` | `value`, `max`, `showValue` | — (read-only) |
31
+ | `ReviewStars` | `value`, `max`, `readOnly` | `onChange` |
32
+ | `StatisticsCard` | `title`, `value`, `trend`, `icon` | — |
33
+ | `Breadcrumb` | `items`, `separator`, `maxItems` | — |
34
+
35
+ ---
36
+
37
+ ## Base Components (shadcn/ui)
38
+
39
+ Standard UI primitives. All follow shadcn patterns.
40
+
41
+ | Component | Usage |
42
+ |-----------|-------|
43
+ | `Button` | `<Button variant="default\|destructive\|outline\|secondary\|ghost\|link" size="default\|sm\|lg\|icon">` |
44
+ | `Input` | `<Input type="text\|email\|password" placeholder="..." />` |
45
+ | `Textarea` | `<Textarea rows={4} />` |
46
+ | `Select` | `<Select options={[{value, label}]} value={v} onChange={fn} />` |
47
+ | `Checkbox` | `<Checkbox checked={bool} onCheckedChange={fn} />` |
48
+ | `Radio` | `<Radio value={v} checked={bool} onChange={fn} />` |
49
+ | `RadioGroup` | Radix-based group: `<RadioGroup value={v} onValueChange={fn}>` |
50
+ | `Switch` | `<Switch checked={bool} onCheckedChange={fn} />` |
51
+ | `Toggle` | `<Toggle pressed={bool} onPressedChange={fn} />` |
52
+ | `Label` | `<Label htmlFor="id">Text</Label>` |
53
+ | `FormField` | Wrapper: label + input + error message |
54
+ | `FormError` | `<FormError message="Validation error" />` |
55
+
56
+ ---
57
+
58
+ ## Layout & Typography
59
+
60
+ | Component | Usage |
61
+ |-----------|-------|
62
+ | `Card` | Container with `CardHeader`, `CardContent`, `CardFooter` subcomponents |
63
+ | `Heading` | `<Heading as="h1">Title</Heading>` (renders h1-h6 via `as` prop) |
64
+ | `Text` | `<Text size="sm\|base\|lg" weight="normal\|medium\|bold">Body text</Text>` |
65
+ | `Link` | `<Link href="/path">Text</Link>` — renders `<a>` (not next/link) |
66
+ | `Badge` | `<Badge variant="default\|secondary\|destructive\|outline">Label</Badge>` |
67
+ | `Separator` | `<Separator orientation="horizontal\|vertical" />` |
68
+ | `AspectRatio` | `<AspectRatio ratio={16/9}><img /></AspectRatio>` |
69
+ | `ScrollArea` | Scrollable container with custom scrollbar |
70
+ | `Skeleton` | Loading placeholder: `<Skeleton className="h-4 w-[200px]" />` |
71
+ | `Progress` | `<Progress value={60} max={100} />` |
72
+
73
+ ---
74
+
75
+ ## Overlay & Navigation
76
+
77
+ | Component | Usage |
78
+ |-----------|-------|
79
+ | `Dialog` | Modal: `Dialog` + `DialogTrigger` + `DialogContent` + `DialogHeader` + `DialogTitle` + `DialogFooter` |
80
+ | `AlertDialog` | Confirmation: `AlertDialog` + `AlertDialogTrigger` + `AlertDialogAction` + `AlertDialogCancel` |
81
+ | `Sheet` | Slide-out drawer: `Sheet` + `SheetTrigger` + `SheetContent` + `SheetHeader` |
82
+ | `Popover` | Floating panel: `Popover` + `PopoverTrigger` + `PopoverContent` |
83
+ | `DropdownMenu` | Context menu: `DropdownMenu` + `DropdownMenuTrigger` + `DropdownMenuContent` + `DropdownMenuItem` |
84
+ | `NavigationMenu` | Mega menu: `NavigationMenu` + `NavigationMenuList` + `NavigationMenuItem` + `NavigationMenuTrigger` |
85
+ | `Tooltip` | `<Tooltip><TooltipTrigger>Hover me</TooltipTrigger><TooltipContent>Info</TooltipContent></Tooltip>` |
86
+ | `HoverCard` | Preview on hover: `HoverCard` + `HoverCardTrigger` + `HoverCardContent` |
87
+ | `Tabs` | `<Tabs defaultValue="tab1"><TabsList><TabsTrigger value="tab1">Tab 1</TabsTrigger></TabsList><TabsContent value="tab1">...</TabsContent></Tabs>` |
88
+ | `Accordion` | Expandable: `Accordion` + `AccordionItem` + `AccordionTrigger` + `AccordionContent` |
89
+ | `Pagination` | `<Pagination currentPage={1} totalPages={10} onPageChange={fn} />` |
90
+
91
+ ---
92
+
93
+ ## Feedback
94
+
95
+ | Component | Usage |
96
+ |-----------|-------|
97
+ | `Alert` | `<Alert variant="default\|success\|warning\|destructive">Message</Alert>` |
98
+ | `LoadingSpinner` | `<LoadingSpinner size="sm\|md\|lg" />` |
99
+ | `EmptyState` | `<EmptyState icon={Icon} title="No items" description="..." action={<Button>CTA</Button>} />` |
100
+ | `Avatar` | `<Avatar><AvatarImage src={url} /><AvatarFallback>JD</AvatarFallback></Avatar>` |
101
+ | `PriceInput` | `<PriceInput value={amount} currency="USD" onChange={fn} />` |
102
+ | `TagInput` | `<TagInput tags={["tag1"]} onTagsChange={fn} />` |
103
+
104
+ ---
105
+
106
+ ## Data Fetching Pattern
107
+
108
+ Components receive data via props from server components. Example:
109
+
110
+ ```tsx
111
+ // app/[locale]/page.tsx (server component)
112
+ import { commerce } from '@/lib/commerce';
113
+ import { backendCircuitBreaker } from '@thorprovider/adapters';
114
+ import { ProductCard } from '@thorprovider/components';
115
+
116
+ export default async function HomePage() {
117
+ const products = await backendCircuitBreaker.execute(
118
+ () => commerce.getProducts({ first: 8 }),
119
+ [],
120
+ );
121
+
122
+ return (
123
+ <div className="grid grid-cols-2 md:grid-cols-4 gap-4">
124
+ {products.map((p) => (
125
+ <ProductCard
126
+ key={p.id}
127
+ title={p.title}
128
+ price={parseFloat(p.priceRange?.minVariantPrice?.amount ?? '0')}
129
+ image={p.featuredImage?.url ?? ''}
130
+ href={`/products/${p.handle}`}
131
+ />
132
+ ))}
133
+ </div>
134
+ );
135
+ }
136
+ ```
137
+
138
+ ## Client Component Pattern (hooks + interactivity)
139
+
140
+ ```tsx
141
+ 'use client';
142
+ // components/add-to-cart-button.tsx
143
+ import { useState } from 'react';
144
+ import { useCart } from '@/lib/cart-provider';
145
+ import { Button } from '@thorprovider/components';
146
+
147
+ export function AddToCartButton({ variantId }: { variantId: string }) {
148
+ const { addItem, isLoading } = useCart();
149
+ const [added, setAdded] = useState(false);
150
+
151
+ async function handleAdd() {
152
+ await addItem(variantId, 1);
153
+ setAdded(true);
154
+ setTimeout(() => setAdded(false), 2000);
155
+ }
156
+
157
+ return (
158
+ <Button onClick={handleAdd} disabled={isLoading}>
159
+ {added ? 'Added!' : 'Add to Cart'}
160
+ </Button>
161
+ );
162
+ }
163
+ ```
164
+
165
+ ## Product Variant Selection Flow
166
+
167
+ ```tsx
168
+ 'use client';
169
+ // Selecting a variant → adding to cart
170
+ import { useState } from 'react';
171
+ import { VariantSelector, QuantitySelector, PriceDisplay } from '@thorprovider/components';
172
+ import { useCart } from '@/lib/cart-provider';
173
+ import type { Product, ProductVariant } from '@thorprovider/types';
174
+
175
+ export function ProductOptions({ product }: { product: Product }) {
176
+ const { addItem } = useCart();
177
+ const [selected, setSelected] = useState<Record<string, string>>({});
178
+ const [quantity, setQuantity] = useState(1);
179
+
180
+ // Find variant matching selected options
181
+ const variant = product.variants.find((v) =>
182
+ v.selectedOptions.every((opt) => selected[opt.name] === opt.value)
183
+ );
184
+
185
+ return (
186
+ <div className="space-y-4">
187
+ {product.options.map((opt) => (
188
+ <VariantSelector
189
+ key={opt.id}
190
+ label={opt.name}
191
+ options={opt.values.map((v) => ({ label: v, value: v }))}
192
+ value={selected[opt.name] ?? ''}
193
+ onChange={(val) => setSelected((prev) => ({ ...prev, [opt.name]: val }))}
194
+ />
195
+ ))}
196
+ {variant && (
197
+ <>
198
+ <PriceDisplay
199
+ price={parseFloat(variant.price.amount)}
200
+ originalPrice={variant.compareAtPrice ? parseFloat(variant.compareAtPrice.amount) : undefined}
201
+ currency={variant.price.currencyCode}
202
+ />
203
+ <QuantitySelector value={quantity} onChange={setQuantity} min={1} max={10} />
204
+ <button onClick={() => addItem(variant.id, quantity)}>Add to Cart</button>
205
+ </>
206
+ )}
207
+ </div>
208
+ );
209
+ }
210
+ ```
211
+
212
+ ## Available Hooks (from @thorprovider/providers via lib/)
213
+
214
+ ### useCart() — `import { useCart } from '@/lib/cart-provider'`
215
+
216
+ | Field | Type | Description |
217
+ |-------|------|-------------|
218
+ | `cart` | `Cart \| null` | Current cart object |
219
+ | `items` | `CartItem[]` | Cart line items array |
220
+ | `totalQuantity` | `number` | Total items in cart |
221
+ | `isLoading` | `boolean` | True during mutations |
222
+ | `error` | `Error \| null` | Last error |
223
+ | `addItem(variantId, qty?)` | `Promise<void>` | Add variant to cart |
224
+ | `updateQuantity(lineItemId, qty)` | `Promise<void>` | Update line item quantity |
225
+ | `removeItem(lineItemId)` | `Promise<void>` | Remove line item |
226
+ | `clearCart()` | `void` | Clear entire cart |
227
+
228
+ ### useAuth() — `import { useAuth } from '@/lib/auth-context'`
229
+
230
+ | Field | Type | Description |
231
+ |-------|------|-------------|
232
+ | `customer` | `Customer \| null` | Current customer |
233
+ | `isAuthenticated` | `boolean` | True if logged in |
234
+ | `loading` | `boolean` | True during mutations |
235
+ | `login(credentials)` | `Promise<void>` | `{ email, password }` |
236
+ | `register(data)` | `Promise<void>` | `{ firstName, lastName, email, password }` |
237
+ | `logout()` | `Promise<void>` | Sign out |
238
+ | `requestPasswordReset(email)` | `Promise<void>` | Send reset email |
239
+ | `resetPassword(token, password)` | `Promise<void>` | Reset with token |
240
+ | `updateCustomer(data)` | `Promise<void>` | Update profile fields |
241
+
242
+ ### useRegion() — `import { useRegion } from '@/lib/region-provider'`
243
+
244
+ | Field | Type | Description |
245
+ |-------|------|-------------|
246
+ | `region` | `Region` | Current region (currency, countries) |
247
+ | `regions` | `Region[]` | All available regions |
248
+ | `setRegion(regionId)` | `void` | Switch region |
249
+
250
+ ### useCommerce() — `import { useCommerce } from '@/lib/commerce-provider'`
251
+
252
+ | Field | Type | Description |
253
+ |-------|------|-------------|
254
+ | `provider` | `CommerceProvider` | Commerce instance for client-side calls |
255
+
256
+ ### useNavigation() — `import { useNavigation } from '@thorprovider/providers'`
257
+
258
+ | Field | Type | Description |
259
+ |-------|------|-------------|
260
+ | `Link` | `Component` | Framework-aware link (renders next/link in Next.js) |
261
+ | `navigate(href)` | `void` | Programmatic navigation |
262
+
263
+ ## Price Formatting
264
+
265
+ `Money.amount` is always a **string** (e.g., `"45.00"`). Convert to number for display components:
266
+
267
+ ```tsx
268
+ const price = parseFloat(product.priceRange.minVariantPrice.amount);
269
+ const currency = product.priceRange.minVariantPrice.currencyCode; // "USD"
270
+
271
+ // Use PriceDisplay component
272
+ <PriceDisplay price={price} currency={currency} />
273
+
274
+ // Or format manually
275
+ new Intl.NumberFormat('en-US', { style: 'currency', currency }).format(price);
276
+ ```
@@ -0,0 +1,53 @@
1
+ # Dependencies — @thorprovider/* Packages
2
+
3
+ ## Quick Reference
4
+
5
+ | Package | Import | Use when |
6
+ |---------|--------|----------|
7
+ | `@thorprovider/types` | `import type { Product } from '@thorprovider/types'` | TypeScript types for domain objects |
8
+ | `@thorprovider/components` | `import { Button } from '@thorprovider/components'` | UI primitives — always check here first |
9
+ | `@thorprovider/providers` | `import { useCart } from '@thorprovider/providers'` | React hooks for commerce state |
10
+ | `@thorprovider/adapters` | `import { backendCircuitBreaker } from '@thorprovider/adapters'` | Resilient backend calls in pages/routes |
11
+
12
+ ## @thorprovider/components — Complete Inventory (55 components)
13
+
14
+ **⚠️ Check this list BEFORE creating any UI component. If it's here, import it — don't recreate it.**
15
+
16
+ **TIER 1 — Base (20):** `Button`, `Input`, `Label`, `Badge`, `Checkbox`, `Radio`, `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `CardFooter`, `Heading`, `Text`, `Link`, `Select`, `Textarea`, `FormField`, `Dialog` (+ `DialogHeader`, `DialogTitle`, `DialogDescription`, `DialogFooter`, `DialogClose`), `Alert`, `Skeleton`
17
+
18
+ **TIER 2 — Composite (10):** `SearchInput`, `PriceInput`, `ProductImage`, `Rating`, `TagInput`, `Pagination`, `StatisticsCard`, `Breadcrumb`, `Tooltip`, `Tabs` (+ `TabsList`, `TabsTrigger`, `TabsContent`)
19
+
20
+ **TIER 3 — Ecommerce (10):** `ProductCard`, `CartItem`, `CartSummary`, `ProductFilter`, `PriceDisplay`, `FormError`, `LoadingSpinner`, `EmptyState`, `ReviewStars`, `QuantitySelector`
21
+
22
+ **TIER 4 — Advanced (20):** `Avatar`, `DropdownMenu`, `Popover`, `AlertDialog`, `Sheet`, `ScrollArea`, `Separator`, `NavigationMenu`, `Progress`, `Switch`, `Toggle`, `HoverCard`, `Accordion`, `AspectRatio`, `RadioGroup`, `CartDrawer`, `ProductQuickView`, `VariantSelector`, `CheckoutStepIndicator`, `WishlistToggle`
23
+
24
+ **Utility:** `cn` (class merging helper)
25
+
26
+ ```
27
+ Need a component?
28
+ ├─ Found above? → import { X } from '@thorprovider/components'
29
+ └─ Not found? → create in components/[feature].tsx
30
+ (compose using @thorprovider/components primitives inside)
31
+ ```
32
+
33
+ ## @thorprovider/providers — Available Hooks
34
+
35
+ ```ts
36
+ import { useCart } from '@thorprovider/providers'; // items, total, addToCart()
37
+ import { useAuth } from '@thorprovider/providers'; // user, login(), logout()
38
+ import { useRegion } from '@thorprovider/providers'; // current region + currency
39
+ import { useNavigation } from '@thorprovider/providers'; // Link, Image (framework-agnostic)
40
+ import { useCommerce } from '@thorprovider/providers'; // commerce provider instance
41
+ ```
42
+
43
+ ## Commerce API + Types
44
+
45
+ For method signatures → see `commerce-api.md`
46
+ For type definitions → see `types.md`
47
+
48
+ Quick start:
49
+ ```ts
50
+ import { commerce } from '@/lib/commerce';
51
+ import { backendCircuitBreaker } from '@thorprovider/adapters';
52
+ import type { Product, Cart, Order, Customer } from '@thorprovider/types';
53
+ ```
@@ -0,0 +1,100 @@
1
+ # Patterns (Code Templates)
2
+
3
+ ## 1. Server Page (Data Fetch)
4
+
5
+ ```tsx
6
+ // app/[locale]/products/page.tsx
7
+ import { backendCircuitBreaker } from '@thorprovider/adapters';
8
+ import { commerce } from '@/lib/commerce';
9
+
10
+ export default async function ProductsPage() {
11
+ const products = await backendCircuitBreaker.execute(
12
+ () => commerce.getProducts({ limit: 20 }),
13
+ [] // shown if backend unreachable
14
+ );
15
+ return <ProductGrid products={products} />;
16
+ }
17
+ ```
18
+
19
+ ❌ Never fetch in client with `useEffect` → causes visible loading flash + worse LCP.
20
+
21
+ ---
22
+
23
+ ## 2. Client Component
24
+
25
+ ```tsx
26
+ // components/product-card.tsx
27
+ 'use client';
28
+ import { useNavigation } from '@thorprovider/providers';
29
+ import { Button, Card } from '@thorprovider/components';
30
+ import type { Product } from '@thorprovider/types';
31
+
32
+ export function ProductCard({ product }: { product: Product }) {
33
+ const { Link, Image } = useNavigation();
34
+ return (
35
+ <Card>
36
+ <Link href={`/products/${product.id}`}>
37
+ <Image src={product.thumbnail} alt={product.title} width={300} height={300} />
38
+ <p>{product.title}</p>
39
+ </Link>
40
+ <Button>Add to cart</Button>
41
+ </Card>
42
+ );
43
+ }
44
+ ```
45
+
46
+ ❌ Never `import Link from 'next/link'` inside `components/` — use `useNavigation()`.
47
+
48
+ ---
49
+
50
+ ## 3. Styling
51
+
52
+ ```tsx
53
+ // ✅ CSS tokens (dark mode + theming work automatically)
54
+ <div style={{ color: 'var(--foreground)', background: 'var(--background)' }} />
55
+ <button className="bg-[var(--primary-9)] hover:bg-[var(--primary-8)]" />
56
+
57
+ // ❌ Hardcoded colors (breaks dark mode)
58
+ <div style={{ color: '#1a1a1a', background: '#ffffff' }} />
59
+ <button className="bg-blue-500 hover:bg-blue-600" />
60
+ ```
61
+
62
+ **Available tokens:** `--background`, `--foreground`, `--border`, `--primary-9/8`, `--success`, `--warning`, `--error`
63
+
64
+ ---
65
+
66
+ ## 4. API Route (GET)
67
+
68
+ ```ts
69
+ // app/api/products/route.ts
70
+ import { backendCircuitBreaker } from '@thorprovider/adapters';
71
+ import { commerce } from '@/lib/commerce';
72
+
73
+ export async function GET() {
74
+ try {
75
+ const products = await backendCircuitBreaker.execute(
76
+ () => commerce.getProducts(),
77
+ []
78
+ );
79
+ return Response.json(products);
80
+ } catch {
81
+ return Response.json({ error: 'Service unavailable' }, { status: 503 });
82
+ }
83
+ }
84
+ ```
85
+
86
+ ---
87
+
88
+ ## 5. Admin Route
89
+
90
+ ```ts
91
+ // app/api/admin/orders/route.ts
92
+ import { adminFetch } from '@/lib/admin/utils/admin-fetch';
93
+
94
+ export async function GET() {
95
+ const res = await adminFetch('/api/admin/orders?limit=20');
96
+ return Response.json(await res.json());
97
+ }
98
+ ```
99
+
100
+ ❌ Never `fetch('/api/admin/...')` directly — `adminFetch` handles credentials + 3x retry.
@@ -0,0 +1,53 @@
1
+ # Project Structure
2
+
3
+ ## Folder Map
4
+
5
+ ```
6
+ app/
7
+ [locale]/
8
+ layout.tsx ← Provider chain (frozen — never reorder)
9
+ page.tsx ← Home page
10
+ products/ ← Add your feature pages here
11
+ api/ ← API routes (server-side only)
12
+
13
+ components/ ← Your page-specific components
14
+ providers/
15
+ app-providers.tsx ← Provider chain composite (frozen)
16
+
17
+ config/
18
+ site.config.ts ← Brand: name, logo, navigation, color preset
19
+
20
+ lib/ ← Infrastructure (don't edit unless adding utilities)
21
+ commerce.ts ← Backend connection
22
+ auth-context.tsx ← Auth provider
23
+ cart-provider.tsx ← Cart provider
24
+
25
+ messages/ ← i18n translation files
26
+ en.json
27
+ es.json
28
+
29
+ src/i18n/
30
+ routing.ts ← Locale list (add new locales here)
31
+ ```
32
+
33
+ ## Where Does X Go?
34
+
35
+ | Task | Location |
36
+ |------|----------|
37
+ | New page | `app/[locale]/[slug]/page.tsx` |
38
+ | Page-specific component | `components/[feature].tsx` |
39
+ | Reusable UI primitive | `@thorprovider/components` first (see `dependencies.md`) |
40
+ | Site name, logo, nav links | `config/site.config.ts` |
41
+ | New language | `messages/[locale].json` + `src/i18n/routing.ts` |
42
+ | API route | `app/api/[route]/route.ts` |
43
+
44
+ ## Component Decision
45
+
46
+ ```
47
+ Need a UI component?
48
+ ├─ Exists in @thorprovider/components? → import { X } from '@thorprovider/components'
49
+ └─ Not found? → create in components/[feature].tsx
50
+ (compose using @thorprovider/components inside)
51
+ ```
52
+
53
+ → See `dependencies.md` for full `@thorprovider/components` inventory.
@@ -0,0 +1,51 @@
1
+ # Rules
2
+
3
+ These rules protect the app's ability to: swap backends without code changes, work in dark mode, survive backend downtime, stay framework-portable, and work in v0 previews.
4
+
5
+ ## Non-Negotiables
6
+
7
+ | Rule | Why | Consequence if broken |
8
+ |------|-----|-----------------------|
9
+ | No backend SDK imports (e.g. `@meduzajs/js-sdk`, `@shopify/api`) | Backend is swappable via adapters | Vendor lock-in; migration requires rewrite |
10
+ | No raw `fetch(COMMERCE_API_URL + '...')` | Raw URLs bypass the adapter layer | No retry, credential leak, lock-in |
11
+ | No `import Link from 'next/link'` in `components/` | Components must be framework-portable | Breaks portability; use `useNavigation()` |
12
+ | Wrap reads in `backendCircuitBreaker.execute(fn, fallback)` | Backend can be intermittently unavailable | Page crashes instead of showing fallback |
13
+ | Use `adminFetch()` for admin API routes | Handles credentials + 3x retry automatically | One transient failure breaks admin panel |
14
+ | No `#hex` / `rgb()` inline colors | CSS tokens enable dark mode + theming | Dark mode breaks; theme non-customizable |
15
+ | Don't re-implement `@thorprovider/components` components | 55 exist with full TypeScript + accessibility | Duplicate code, inconsistent UI — see `dependencies.md` for full list |
16
+ | Use relative imports for `lib/` files (never bare paths) | v0 bundler only resolves relative imports | V0 preview fails with "Unable to resolve specifier" error |
17
+
18
+ ## Provider Chain (Frozen Order)
19
+
20
+ **File:** `components/providers/app-providers.tsx`
21
+
22
+ ```tsx
23
+ <NextIntlClientProvider>
24
+ <ClientCommerceProvider>
25
+ <ClientRegionProvider>
26
+ <AuthProvider>
27
+ <ClientCartProvider>
28
+ <ClientNavigationProvider>
29
+ {children}
30
+ </ClientNavigationProvider>
31
+ </ClientCartProvider>
32
+ </AuthProvider>
33
+ </ClientRegionProvider>
34
+ </ClientCommerceProvider>
35
+ </NextIntlClientProvider>
36
+ ```
37
+
38
+ Each provider requires the context of the prior one. Reordering = runtime crash.
39
+ To add a custom provider → wrap `{children}` **inside** `ClientNavigationProvider`.
40
+
41
+ ## Pre-Commit Checklist
42
+
43
+ - [ ] Checked `@thorprovider/components` inventory before creating a new UI component?
44
+ - [ ] All `commerce.get*()` reads wrapped in `backendCircuitBreaker.execute(fn, fallback)`?
45
+ - [ ] No backend SDK imports (`@meduzajs/js-sdk`, `@shopify/api`, etc.)?
46
+ - [ ] No raw `fetch(COMMERCE_API_URL...)` or bare admin `fetch()`?
47
+ - [ ] No `import Link/Image from 'next/*'` inside `components/`?
48
+ - [ ] No hardcoded `#hex`, `rgb()`, or Tailwind arbitrary non-token colors?
49
+ - [ ] `yarn type-check` passes?
50
+ - [ ] Server components fetch; client components receive data via props?
51
+ - [ ] Provider chain order unchanged?