@thorprovider/create-thor-app 3.1.1 → 3.1.3
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 +11 -14
- package/package.json +5 -3
- package/templates/default/ai-validator.json +57 -82
- package/templates/default/docs/commerce-api.md +8 -0
- package/templates/default/docs/patterns.md +4 -4
- package/templates/default/docs/project-structure.md +13 -11
- package/templates/default/docs/rules.md +3 -3
- package/templates/default/docs/types.md +1000 -125
package/README.md
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: create-thor-app
|
|
3
3
|
purpose: CLI scaffolding tool for generating new Thor Commerce applications from the core template
|
|
4
|
-
lastReviewed: "2026-04-
|
|
4
|
+
lastReviewed: "2026-04-29"
|
|
5
5
|
---
|
|
6
6
|
|
|
7
7
|
# create-thor-app
|
|
@@ -16,20 +16,17 @@ Supports **dual-mode** operation:
|
|
|
16
16
|
|
|
17
17
|
## Installation
|
|
18
18
|
|
|
19
|
-
###
|
|
19
|
+
### npm (Public Package)
|
|
20
20
|
|
|
21
|
-
This package is published to
|
|
21
|
+
This package is published publicly to npm:
|
|
22
22
|
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
```bash
|
|
31
|
-
npm install -g @thorprovider/create-thor-app
|
|
32
|
-
```
|
|
23
|
+
```bash
|
|
24
|
+
# Run directly without installing (recommended)
|
|
25
|
+
npx @thorprovider/create-thor-app my-store
|
|
26
|
+
|
|
27
|
+
# Or install globally
|
|
28
|
+
npm install -g @thorprovider/create-thor-app
|
|
29
|
+
```
|
|
33
30
|
|
|
34
31
|
### From Monorepo
|
|
35
32
|
|
|
@@ -80,7 +77,7 @@ yarn create:app --name my-store \
|
|
|
80
77
|
--skip-install \
|
|
81
78
|
--skip-remote \
|
|
82
79
|
--skip-vercel \
|
|
83
|
-
--
|
|
80
|
+
--no-context
|
|
84
81
|
|
|
85
82
|
# Full backend setup in one command
|
|
86
83
|
yarn create:app --name my-store \
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@thorprovider/create-thor-app",
|
|
3
|
-
"version": "3.1.
|
|
3
|
+
"version": "3.1.3",
|
|
4
4
|
"description": "CLI to scaffold a new Thor Commerce application from @thorprovider/core template",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": "./dist/index.js",
|
|
@@ -15,7 +15,8 @@
|
|
|
15
15
|
"scripts": {
|
|
16
16
|
"build": "tsup",
|
|
17
17
|
"dev": "tsup --watch",
|
|
18
|
-
"type-check": "tsc --noEmit"
|
|
18
|
+
"type-check": "tsc --noEmit",
|
|
19
|
+
"generate:types-doc": "tsx scripts/generate-types-doc.ts"
|
|
19
20
|
},
|
|
20
21
|
"dependencies": {
|
|
21
22
|
"commander": "^13.1.0"
|
|
@@ -23,10 +24,11 @@
|
|
|
23
24
|
"devDependencies": {
|
|
24
25
|
"@types/node": "^22.0.0",
|
|
25
26
|
"tsup": "^8.0.0",
|
|
27
|
+
"tsx": "^4.21.0",
|
|
26
28
|
"typescript": "^5.0.0"
|
|
27
29
|
},
|
|
28
30
|
"publishConfig": {
|
|
29
|
-
"access": "
|
|
31
|
+
"access": "public",
|
|
30
32
|
"registry": "https://registry.npmjs.org/"
|
|
31
33
|
},
|
|
32
34
|
"repository": {
|
|
@@ -1,76 +1,82 @@
|
|
|
1
1
|
{
|
|
2
|
-
"version": "1.
|
|
3
|
-
"description": "V0 Stop Hooks validation criteria for Thor Commerce projects",
|
|
2
|
+
"version": "1.1.0",
|
|
3
|
+
"description": "V0 Stop Hooks validation criteria for Thor Commerce storefront projects",
|
|
4
4
|
"maxRetries": 2,
|
|
5
5
|
"retryModelId": "v0-1.5-sm",
|
|
6
6
|
"architecturalRules": [
|
|
7
7
|
{
|
|
8
|
-
"id": "no-
|
|
9
|
-
"filePattern": "
|
|
10
|
-
"pattern": "
|
|
11
|
-
"description": "
|
|
8
|
+
"id": "no-next-link-in-components",
|
|
9
|
+
"filePattern": "components/**/*.tsx",
|
|
10
|
+
"pattern": "import.*Link.*from.*next/link|from\\s+['\"]next/link['\"]",
|
|
11
|
+
"description": "Never import next/link in components/ — use useNavigation() from @thorprovider/providers instead"
|
|
12
12
|
},
|
|
13
13
|
{
|
|
14
|
-
"id": "no-
|
|
15
|
-
"filePattern": "
|
|
16
|
-
"pattern": "
|
|
17
|
-
"description": "
|
|
14
|
+
"id": "no-next-image-in-components",
|
|
15
|
+
"filePattern": "components/**/*.tsx",
|
|
16
|
+
"pattern": "import.*Image.*from.*next/image|from\\s+['\"]next/image['\"]",
|
|
17
|
+
"description": "Never import next/image in components/ — use useNavigation() which provides a framework-aware Image component"
|
|
18
18
|
},
|
|
19
19
|
{
|
|
20
|
-
"id": "
|
|
21
|
-
"filePattern": "
|
|
22
|
-
"pattern": "
|
|
23
|
-
"description": "
|
|
24
|
-
"required": false
|
|
20
|
+
"id": "no-backend-sdk-imports",
|
|
21
|
+
"filePattern": "**/*.{ts,tsx}",
|
|
22
|
+
"pattern": "from\\s+['\"]@medusajs/js-sdk['\"]|from\\s+['\"]@shopify/api['\"]",
|
|
23
|
+
"description": "Never import backend SDKs directly — use commerce from @/lib/commerce (backend is swappable via adapters)"
|
|
25
24
|
},
|
|
26
25
|
{
|
|
27
|
-
"id": "no-raw-
|
|
28
|
-
"filePattern": "
|
|
29
|
-
"pattern": "
|
|
30
|
-
"description": "
|
|
26
|
+
"id": "no-raw-commerce-fetch",
|
|
27
|
+
"filePattern": "**/*.{ts,tsx}",
|
|
28
|
+
"pattern": "fetch\\(.*NEXT_PUBLIC_COMMERCE_API_URL|fetch\\(.*process\\.env\\.NEXT_PUBLIC_COMMERCE_API",
|
|
29
|
+
"description": "Never call the commerce backend directly via fetch — use commerce.* methods from @/lib/commerce"
|
|
31
30
|
},
|
|
32
31
|
{
|
|
33
|
-
"id": "
|
|
34
|
-
"filePattern": "
|
|
35
|
-
"pattern": "
|
|
36
|
-
"description": "
|
|
32
|
+
"id": "circuit-breaker-on-reads",
|
|
33
|
+
"filePattern": "app/**/*.{ts,tsx}",
|
|
34
|
+
"pattern": "await commerce\\.get(?!.*backendCircuitBreaker)",
|
|
35
|
+
"description": "All commerce.get*() read operations must be wrapped with backendCircuitBreaker.execute(fn, fallback)",
|
|
36
|
+
"required": true
|
|
37
37
|
},
|
|
38
38
|
{
|
|
39
|
-
"id": "no-
|
|
39
|
+
"id": "no-hardcoded-hex-colors",
|
|
40
40
|
"filePattern": "components/**/*.tsx",
|
|
41
|
-
"pattern": "
|
|
42
|
-
"description": "Use
|
|
41
|
+
"pattern": "style=\\{\\{.*color.*#[0-9a-fA-F]{3,6}|style=\\{\\{.*background.*#[0-9a-fA-F]{3,6}",
|
|
42
|
+
"description": "Use CSS tokens (var(--foreground), var(--background), etc.) instead of hardcoded hex colors — required for dark mode"
|
|
43
43
|
},
|
|
44
44
|
{
|
|
45
|
-
"id": "
|
|
46
|
-
"filePattern": "
|
|
47
|
-
"pattern": "
|
|
48
|
-
"description": "
|
|
45
|
+
"id": "no-inline-rgb-colors",
|
|
46
|
+
"filePattern": "components/**/*.tsx",
|
|
47
|
+
"pattern": "style=\\{\\{.*color.*rgb\\(|style=\\{\\{.*background.*rgb\\(",
|
|
48
|
+
"description": "Use CSS tokens instead of rgb() colors — required for dark mode and theming"
|
|
49
49
|
},
|
|
50
50
|
{
|
|
51
|
-
"id": "
|
|
52
|
-
"filePattern": "
|
|
53
|
-
"pattern": "
|
|
54
|
-
"description": "
|
|
51
|
+
"id": "no-frozen-lib-modifications",
|
|
52
|
+
"filePattern": "lib/commerce.ts",
|
|
53
|
+
"pattern": "createProvider\\(",
|
|
54
|
+
"description": "lib/commerce.ts is frozen — createProvider() must only be called once in this file",
|
|
55
55
|
"required": false
|
|
56
56
|
},
|
|
57
57
|
{
|
|
58
|
-
"id": "no-
|
|
59
|
-
"filePattern": "**/*.ts",
|
|
60
|
-
"pattern": "
|
|
61
|
-
"description": "
|
|
58
|
+
"id": "no-any-type",
|
|
59
|
+
"filePattern": "**/*.{ts,tsx}",
|
|
60
|
+
"pattern": ":\\s*any(?![a-zA-Z])",
|
|
61
|
+
"description": "Avoid 'any' type — use proper TypeScript types from @thorprovider/types"
|
|
62
|
+
},
|
|
63
|
+
{
|
|
64
|
+
"id": "no-var-declaration",
|
|
65
|
+
"filePattern": "**/*.{ts,tsx}",
|
|
66
|
+
"pattern": "\\bvar\\s+",
|
|
67
|
+
"description": "Use const/let instead of var"
|
|
62
68
|
},
|
|
63
69
|
{
|
|
64
|
-
"id": "use-
|
|
65
|
-
"filePattern": "
|
|
66
|
-
"pattern": "
|
|
67
|
-
"description": "
|
|
70
|
+
"id": "use-product-handle-in-urls",
|
|
71
|
+
"filePattern": "**/*.tsx",
|
|
72
|
+
"pattern": "/products/\\$\\{.*\\.id\\}|/products/\\$\\{.*product\\.id\\}",
|
|
73
|
+
"description": "Use product.handle for product URLs (not product.id) — handle is the URL-safe slug"
|
|
68
74
|
},
|
|
69
75
|
{
|
|
70
76
|
"id": "no-client-env-vars",
|
|
71
77
|
"filePattern": "components/**/*.tsx",
|
|
72
78
|
"pattern": "process\\.env\\.[A-Z_]*(?!NEXT_PUBLIC)",
|
|
73
|
-
"description": "Client components cannot access non-NEXT_PUBLIC env vars"
|
|
79
|
+
"description": "Client components cannot access non-NEXT_PUBLIC env vars — they are only available server-side"
|
|
74
80
|
},
|
|
75
81
|
{
|
|
76
82
|
"id": "use-cn-utility",
|
|
@@ -78,54 +84,23 @@
|
|
|
78
84
|
"pattern": "className=\\{.*\\+.*\\}",
|
|
79
85
|
"description": "Use cn() utility for dynamic classNames instead of string concatenation"
|
|
80
86
|
},
|
|
81
|
-
{
|
|
82
|
-
"id": "no-inline-styles",
|
|
83
|
-
"filePattern": "components/**/*.tsx",
|
|
84
|
-
"pattern": "style=\\{\\{",
|
|
85
|
-
"description": "Use Tailwind CSS classes instead of inline styles"
|
|
86
|
-
},
|
|
87
87
|
{
|
|
88
88
|
"id": "proper-error-handling",
|
|
89
89
|
"filePattern": "app/api/**/*.ts",
|
|
90
90
|
"pattern": "catch\\s*\\(\\s*\\)",
|
|
91
|
-
"description": "Error handlers must capture
|
|
92
|
-
},
|
|
93
|
-
{
|
|
94
|
-
"id": "use-zod-validation",
|
|
95
|
-
"filePattern": "app/api/**/*.ts",
|
|
96
|
-
"pattern": "JSON\\.parse|typeof.*===.*string",
|
|
97
|
-
"description": "Use Zod for request validation instead of manual type checking"
|
|
91
|
+
"description": "Error handlers must capture errors (not empty catch blocks)"
|
|
98
92
|
},
|
|
99
93
|
{
|
|
100
|
-
"id": "no-
|
|
101
|
-
"filePattern": "**/*.
|
|
102
|
-
"pattern": "
|
|
103
|
-
"description": "
|
|
104
|
-
},
|
|
105
|
-
{
|
|
106
|
-
"id": "use-next-image",
|
|
107
|
-
"filePattern": "components/**/*.tsx",
|
|
108
|
-
"pattern": "<img\\s",
|
|
109
|
-
"description": "Use next/image Image component instead of <img> tag"
|
|
94
|
+
"id": "no-var-declaration-tsx",
|
|
95
|
+
"filePattern": "**/*.tsx",
|
|
96
|
+
"pattern": "\\bvar\\s+",
|
|
97
|
+
"description": "Use const/let instead of var"
|
|
110
98
|
},
|
|
111
99
|
{
|
|
112
|
-
"id": "
|
|
100
|
+
"id": "no-useeffect-commerce-fetch",
|
|
113
101
|
"filePattern": "components/**/*.tsx",
|
|
114
|
-
"pattern": "
|
|
115
|
-
"description": "
|
|
116
|
-
},
|
|
117
|
-
{
|
|
118
|
-
"id": "proper-async-await",
|
|
119
|
-
"filePattern": "app/api/**/*.ts",
|
|
120
|
-
"pattern": "\\.then\\(|Promise\\.all\\(",
|
|
121
|
-
"description": "Use async/await instead of .then() chains",
|
|
122
|
-
"required": false
|
|
123
|
-
},
|
|
124
|
-
{
|
|
125
|
-
"id": "no-var-declaration",
|
|
126
|
-
"filePattern": "**/*.ts",
|
|
127
|
-
"pattern": "\\bvar\\s+",
|
|
128
|
-
"description": "Use const/let instead of var"
|
|
102
|
+
"pattern": "useEffect[\\s\\S]{0,200}commerce\\.|useEffect[\\s\\S]{0,200}fetch\\([^)]*COMMERCE",
|
|
103
|
+
"description": "Never fetch commerce data inside useEffect in components — fetch in server components (app/*/page.tsx) and pass data as props. useEffect + commerce fetch causes loading flash and worse LCP."
|
|
129
104
|
}
|
|
130
105
|
]
|
|
131
106
|
}
|
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
# Commerce API
|
|
2
2
|
|
|
3
|
+
**lastReviewed**: 2026-04-29
|
|
4
|
+
|
|
3
5
|
All backend access goes through `commerce` (from `@/lib/commerce`) + `backendCircuitBreaker` (from `@thorprovider/adapters`).
|
|
4
6
|
|
|
5
7
|
## Setup (already wired in the app)
|
|
@@ -19,6 +21,12 @@ const result = await backendCircuitBreaker.execute(() => commerce.method(...), f
|
|
|
19
21
|
const result = await commerce.method(...);
|
|
20
22
|
```
|
|
21
23
|
|
|
24
|
+
**Admin methods** require `COMMERCE_ADMIN_API_KEY` set in `.env`:
|
|
25
|
+
```bash
|
|
26
|
+
COMMERCE_ADMIN_API_KEY=your_admin_api_key
|
|
27
|
+
```
|
|
28
|
+
Without this key, admin config is not initialized and admin methods will not be available.
|
|
29
|
+
|
|
22
30
|
---
|
|
23
31
|
|
|
24
32
|
## Storefront Methods
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: "Patterns (Code Templates)"
|
|
3
3
|
purpose: "Canonical code templates for common patterns like server pages, client components, and commerce data fetching"
|
|
4
|
-
lastReviewed: "2026-04-
|
|
4
|
+
lastReviewed: "2026-04-29"
|
|
5
5
|
---
|
|
6
6
|
|
|
7
7
|
# Patterns (Code Templates)
|
|
@@ -15,7 +15,7 @@ import { commerce } from '@/lib/commerce';
|
|
|
15
15
|
|
|
16
16
|
export default async function ProductsPage() {
|
|
17
17
|
const products = await backendCircuitBreaker.execute(
|
|
18
|
-
() => commerce.getProducts({
|
|
18
|
+
() => commerce.getProducts({ first: 20 }),
|
|
19
19
|
[] // shown if backend unreachable
|
|
20
20
|
);
|
|
21
21
|
return <ProductGrid products={products} />;
|
|
@@ -39,8 +39,8 @@ export function ProductCard({ product }: { product: Product }) {
|
|
|
39
39
|
const { Link, Image } = useNavigation();
|
|
40
40
|
return (
|
|
41
41
|
<Card>
|
|
42
|
-
<Link href={`/products/${product.
|
|
43
|
-
<Image src={product.
|
|
42
|
+
<Link href={`/products/${product.handle}`}>
|
|
43
|
+
<Image src={product.featuredImage?.url ?? ''} alt={product.featuredImage?.altText ?? product.title} width={300} height={300} />
|
|
44
44
|
<p>{product.title}</p>
|
|
45
45
|
</Link>
|
|
46
46
|
<Button>Add to cart</Button>
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: "Project Structure"
|
|
3
3
|
purpose: "Folder map and file ownership reference for generated Thor Commerce storefronts"
|
|
4
|
-
lastReviewed: "2026-04-
|
|
4
|
+
lastReviewed: "2026-04-29"
|
|
5
5
|
---
|
|
6
6
|
|
|
7
7
|
# Project Structure
|
|
@@ -31,17 +31,19 @@ components/ ← Your page-specific components
|
|
|
31
31
|
config/
|
|
32
32
|
site.config.ts ← Brand: name, logo, navigation, color preset
|
|
33
33
|
|
|
34
|
-
lib/ ← Infrastructure (frozen unless adding utilities)
|
|
35
|
-
commerce.ts ← Commerce singleton (createProvider, lazy proxy)
|
|
36
|
-
commerce-provider.tsx ← ClientCommerceProvider + useCommerce hook
|
|
37
|
-
region-provider.tsx ← ClientRegionProvider + useRegion hook
|
|
38
|
-
auth-context.tsx ← AuthProvider + useAuth hook
|
|
39
|
-
cart-provider.tsx ← ClientCartProvider + useCart hook
|
|
40
|
-
storefront-config.ts ← Backend-driven storefront config fetch (theme accent, cached)
|
|
41
|
-
region-detection.ts ← IP-based region detection from Vercel/Cloudflare headers
|
|
42
|
-
regions-config.ts ← Auto-generated locale→region map
|
|
43
|
-
env.ts ← Zod-validated environment variable schema
|
|
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
44
|
utils.ts ← cn() class merging helper
|
|
45
|
+
|
|
46
|
+
proxy.ts ← Next.js edge middleware: detects backend unavailability, redirects to /backend-unavailable
|
|
45
47
|
```
|
|
46
48
|
|
|
47
49
|
## Where Does X Go?
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: "Rules"
|
|
3
3
|
purpose: "Non-negotiable constraints that protect backend swappability, dark mode, and framework portability"
|
|
4
|
-
lastReviewed: "2026-04-
|
|
4
|
+
lastReviewed: "2026-04-29"
|
|
5
5
|
---
|
|
6
6
|
|
|
7
7
|
# Rules
|
|
@@ -12,7 +12,7 @@ These rules protect the app's ability to: swap backends without code changes, wo
|
|
|
12
12
|
|
|
13
13
|
| Rule | Why | Consequence if broken |
|
|
14
14
|
|------|-----|-----------------------|
|
|
15
|
-
| No backend SDK imports (e.g. `@
|
|
15
|
+
| No backend SDK imports (e.g. `@medusajs/js-sdk`, `@shopify/api`) | Backend is swappable via adapters | Vendor lock-in; migration requires rewrite |
|
|
16
16
|
| No raw `fetch(COMMERCE_API_URL + '...')` | Raw URLs bypass the adapter layer | No retry, credential leak, lock-in |
|
|
17
17
|
| No `import Link from 'next/link'` in `components/` | Components must be framework-portable | Breaks portability; use `useNavigation()` |
|
|
18
18
|
| Wrap reads in `backendCircuitBreaker.execute(fn, fallback)` | Backend can be intermittently unavailable | Page crashes instead of showing fallback |
|
|
@@ -55,7 +55,7 @@ To add a custom provider → wrap `{children}` **inside** `ClientNavigationProvi
|
|
|
55
55
|
|
|
56
56
|
- [ ] Checked `@thorprovider/components` inventory before creating a new UI component?
|
|
57
57
|
- [ ] All `commerce.get*()` reads wrapped in `backendCircuitBreaker.execute(fn, fallback)`?
|
|
58
|
-
- [ ] No backend SDK imports (`@
|
|
58
|
+
- [ ] No backend SDK imports (`@medusajs/js-sdk`, `@shopify/api`, etc.)?
|
|
59
59
|
- [ ] No raw `fetch(COMMERCE_API_URL...)` calls?
|
|
60
60
|
- [ ] No `import Link/Image from 'next/*'` inside `components/`?
|
|
61
61
|
- [ ] No hardcoded `#hex`, `rgb()`, or Tailwind arbitrary non-token colors?
|