@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.
- package/README.md +470 -0
- package/dist/index.js +1054 -0
- package/package.json +46 -0
- package/templates/default/.env.example +56 -0
- package/templates/default/.eslintrc.json +43 -0
- package/templates/default/README.md +151 -0
- package/templates/default/app/api/revalidate/route.ts +64 -0
- package/templates/default/app/backend-unavailable/page.tsx +85 -0
- package/templates/default/app/error.tsx +58 -0
- package/templates/default/app/global-error.tsx +208 -0
- package/templates/default/app/globals.css +125 -0
- package/templates/default/app/layout.tsx +50 -0
- package/templates/default/app/not-found.tsx +31 -0
- package/templates/default/app/page.tsx +124 -0
- package/templates/default/components/providers/app-providers.tsx +77 -0
- package/templates/default/components/providers/navigation-provider.tsx +37 -0
- package/templates/default/config/site.config.ts +156 -0
- package/templates/default/docs/README.md +46 -0
- package/templates/default/docs/commerce-api.md +243 -0
- package/templates/default/docs/components.md +276 -0
- package/templates/default/docs/dependencies.md +53 -0
- package/templates/default/docs/patterns.md +100 -0
- package/templates/default/docs/project-structure.md +53 -0
- package/templates/default/docs/rules.md +51 -0
- package/templates/default/docs/types.md +329 -0
- package/templates/default/lib/auth-context.tsx +213 -0
- package/templates/default/lib/cart-provider.tsx +53 -0
- package/templates/default/lib/commerce-provider.tsx +48 -0
- package/templates/default/lib/commerce.ts +165 -0
- package/templates/default/lib/env.ts +147 -0
- package/templates/default/lib/region-detection.ts +80 -0
- package/templates/default/lib/region-provider.tsx +53 -0
- package/templates/default/lib/regions-config.ts +48 -0
- package/templates/default/lib/storefront-config.ts +54 -0
- package/templates/default/lib/utils.ts +10 -0
- package/templates/default/next-env.d.ts +6 -0
- package/templates/default/next.config.mjs +51 -0
- package/templates/default/package.json +42 -0
- package/templates/default/postcss.config.mjs +8 -0
- package/templates/default/proxy.ts +155 -0
- package/templates/default/scripts/generate-regions-config.ts +498 -0
- 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?
|