@thorprovider/create-thor-app 4.0.0 → 4.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +6 -55
- package/dist/index.js +154 -626
- package/package.json +1 -1
- package/templates/default/.agents/AGENTS.md +27 -0
- package/templates/default/.env.example +8 -30
- package/templates/default/.eslintrc.json +20 -27
- package/templates/default/README.md +52 -123
- 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 +10 -119
- package/templates/default/components/providers/app-providers.tsx +19 -68
- package/templates/default/components/providers/cart-provider.tsx +143 -0
- package/templates/default/components/providers/commerce-provider.tsx +33 -0
- package/templates/default/components/providers/region-provider.tsx +105 -0
- package/templates/default/docs/README.md +46 -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 +43 -42
- package/templates/default/docs/types.md +105 -1024
- package/templates/default/lib/commerce.ts +33 -132
- package/templates/default/lib/env.ts +24 -94
- package/templates/default/lib/utils.ts +18 -0
- package/templates/default/next-env.d.ts +1 -1
- 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: "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,65 @@
|
|
|
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 |
|
|
21
27
|
|
|
22
28
|
## Provider Chain (Frozen Order)
|
|
23
29
|
|
|
24
|
-
|
|
30
|
+
**File:** `components/providers/app-providers.tsx`
|
|
25
31
|
|
|
26
32
|
```tsx
|
|
27
|
-
|
|
28
|
-
<
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
</
|
|
33
|
+
<CommerceProvider>
|
|
34
|
+
<RegionProvider>
|
|
35
|
+
<CartProvider>
|
|
36
|
+
{children}
|
|
37
|
+
</CartProvider>
|
|
38
|
+
</RegionProvider>
|
|
39
|
+
</CommerceProvider>
|
|
33
40
|
```
|
|
34
41
|
|
|
35
|
-
|
|
42
|
+
CartProvider and RegionProvider depend on commerce. Reordering = runtime crash.
|
|
43
|
+
To add a provider → wrap `{children}` **inside** `CartProvider`.
|
|
36
44
|
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
<AuthProvider>
|
|
41
|
-
<ClientCartProvider>
|
|
42
|
-
<ClientNavigationProvider>
|
|
43
|
-
{children}
|
|
44
|
-
</ClientNavigationProvider>
|
|
45
|
-
</ClientCartProvider>
|
|
46
|
-
</AuthProvider>
|
|
47
|
-
</ClientRegionProvider>
|
|
48
|
-
</ClientCommerceProvider>
|
|
49
|
-
```
|
|
45
|
+
## Frozen Files
|
|
46
|
+
|
|
47
|
+
Never modify these — they are infrastructure:
|
|
50
48
|
|
|
51
|
-
|
|
52
|
-
|
|
49
|
+
| File | Purpose |
|
|
50
|
+
|------|---------|
|
|
51
|
+
| `lib/commerce.ts` | Commerce singleton (createProvider + lazy proxy) |
|
|
52
|
+
| `lib/env.ts` | Zod-validated environment schema |
|
|
53
|
+
| `components/providers/app-providers.tsx` | Provider chain composite |
|
|
53
54
|
|
|
54
55
|
## Pre-Commit Checklist
|
|
55
56
|
|
|
56
|
-
- [ ]
|
|
57
|
-
- [ ]
|
|
58
|
-
- [ ] No backend SDK imports (`@medusajs/js-sdk`, `@shopify/api`, etc.)?
|
|
57
|
+
- [ ] No `@thorprovider/components` or `@thorprovider/providers` imports?
|
|
58
|
+
- [ ] No backend SDK imports (`@medusajs/*`, `@shopify/*`)?
|
|
59
59
|
- [ ] No raw `fetch(COMMERCE_API_URL...)` calls?
|
|
60
|
-
- [ ]
|
|
61
|
-
- [ ]
|
|
62
|
-
- [ ]
|
|
60
|
+
- [ ] All prices rendered via `formatPrice()`?
|
|
61
|
+
- [ ] Using `product.handle` in URLs?
|
|
62
|
+
- [ ] No hardcoded hex/rgb colors?
|
|
63
|
+
- [ ] Types from `@thorprovider/types` (not redefined locally)?
|
|
64
|
+
- [ ] `tsc --noEmit` passes?
|
|
63
65
|
- [ ] Server components fetch; client components receive data via props?
|
|
64
|
-
- [ ] Provider chain order unchanged?
|