@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.
Files changed (48) hide show
  1. package/README.md +6 -55
  2. package/dist/index.js +154 -626
  3. package/package.json +1 -1
  4. package/templates/default/.agents/AGENTS.md +27 -0
  5. package/templates/default/.env.example +8 -30
  6. package/templates/default/.eslintrc.json +20 -27
  7. package/templates/default/README.md +52 -123
  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 +10 -119
  17. package/templates/default/components/providers/app-providers.tsx +19 -68
  18. package/templates/default/components/providers/cart-provider.tsx +143 -0
  19. package/templates/default/components/providers/commerce-provider.tsx +33 -0
  20. package/templates/default/components/providers/region-provider.tsx +105 -0
  21. package/templates/default/docs/README.md +46 -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 +43 -42
  26. package/templates/default/docs/types.md +105 -1024
  27. package/templates/default/lib/commerce.ts +33 -132
  28. package/templates/default/lib/env.ts +24 -94
  29. package/templates/default/lib/utils.ts +18 -0
  30. package/templates/default/next-env.d.ts +1 -1
  31. package/templates/default/next.config.ts +7 -0
  32. package/templates/default/package.json +2 -8
  33. package/templates/default/registry.json +6 -0
  34. package/templates/default/styles/tokens.css +81 -0
  35. package/templates/default/components/providers/navigation-provider.tsx +0 -37
  36. package/templates/default/config/site.config.ts +0 -156
  37. package/templates/default/docs/components.md +0 -282
  38. package/templates/default/docs/dependencies.md +0 -61
  39. package/templates/default/lib/auth-context.tsx +0 -213
  40. package/templates/default/lib/cart-provider.tsx +0 -53
  41. package/templates/default/lib/commerce-provider.tsx +0 -48
  42. package/templates/default/lib/region-detection.ts +0 -73
  43. package/templates/default/lib/region-provider.tsx +0 -53
  44. package/templates/default/lib/regions-config.ts +0 -48
  45. package/templates/default/lib/storefront-config.ts +0 -54
  46. package/templates/default/next.config.mjs +0 -51
  47. package/templates/default/proxy.ts +0 -155
  48. 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 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,65 @@
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 |
21
27
 
22
28
  ## Provider Chain (Frozen Order)
23
29
 
24
- Root layout (`app/layout.tsx`) wraps the full tree with `ThemeProvider`, then delegates to `AppProviders`:
30
+ **File:** `components/providers/app-providers.tsx`
25
31
 
26
32
  ```tsx
27
- // app/layout.tsx
28
- <ThemeProvider preset={siteConfig.preset}>
29
- <AppProviders initialRegionId={initialRegionId}>
30
- {children}
31
- </AppProviders>
32
- </ThemeProvider>
33
+ <CommerceProvider>
34
+ <RegionProvider>
35
+ <CartProvider>
36
+ {children}
37
+ </CartProvider>
38
+ </RegionProvider>
39
+ </CommerceProvider>
33
40
  ```
34
41
 
35
- **File:** `components/providers/app-providers.tsx`
42
+ CartProvider and RegionProvider depend on commerce. Reordering = runtime crash.
43
+ To add a provider → wrap `{children}` **inside** `CartProvider`.
36
44
 
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
- ```
45
+ ## Frozen Files
46
+
47
+ Never modify these — they are infrastructure:
50
48
 
51
- Each provider depends on the context of the prior one. Reordering = runtime crash.
52
- To add a custom provider → wrap `{children}` **inside** `ClientNavigationProvider`.
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
- - [ ] 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.)?
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
- - [ ] No `import Link/Image from 'next/*'` inside `components/`?
61
- - [ ] No hardcoded `#hex`, `rgb()`, or Tailwind arbitrary non-token colors?
62
- - [ ] `yarn type-check` passes?
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?