@thorprovider/create-thor-app 3.1.2 → 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 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-27"
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
- ### GitHub Packages (Recommended for Internal Use)
19
+ ### npm (Public Package)
20
20
 
21
- This package is published to GitHub Packages with restricted access (`@thorprovider` scope).
21
+ This package is published publicly to npm:
22
22
 
23
- **Setup** (one-time):
24
- 1. Create a GitHub personal access token (PAT) with `read:packages` scope
25
- 2. Add to your shell profile (`~/.bashrc` / `~/.zshrc`):
26
- ```bash
27
- export NODE_AUTH_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
28
- ```
29
- 3. Install globally (optional):
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
- --skip-v0-context
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.2",
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,6 +24,7 @@
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": {
@@ -1,76 +1,82 @@
1
1
  {
2
- "version": "1.0.0",
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-console-in-api",
9
- "filePattern": "app/api/**/*.ts",
10
- "pattern": "console\\.",
11
- "description": "Console statements not allowed in API routes (use logger instead)"
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-console-in-lib",
15
- "filePattern": "lib/**/*.ts",
16
- "pattern": "console\\.",
17
- "description": "Console statements not allowed in lib (use logger instead)"
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": "logger-import-in-api",
21
- "filePattern": "app/api/**/*.ts",
22
- "pattern": "import.*logger.*from.*@/lib/logger",
23
- "description": "API routes must import logger from @/lib/logger",
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-sql",
28
- "filePattern": "lib/**/*.ts",
29
- "pattern": "sql`|sql\\(|raw\\(",
30
- "description": "Raw SQL not allowed (use Drizzle ORM instead)"
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": "no-moment-js",
34
- "filePattern": "**/*.ts",
35
- "pattern": "from\\s+['\"]moment['\"]|import.*moment",
36
- "description": "moment.js not allowed (use native Date or date-fns)"
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-manual-classname",
39
+ "id": "no-hardcoded-hex-colors",
40
40
  "filePattern": "components/**/*.tsx",
41
- "pattern": "className=\\{`.*\\$\\{.*\\}`\\}|className=\\{.*\\+.*\\}",
42
- "description": "Use cn() utility instead of manual string concatenation for classNames"
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": "use-drizzle-orm",
46
- "filePattern": "lib/db/**/*.ts",
47
- "pattern": "query\\(|execute\\(|raw\\(",
48
- "description": "Database operations must use Drizzle ORM (no raw queries)"
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": "auth-ownership-check",
52
- "filePattern": "app/api/**/*.ts",
53
- "pattern": "getChatOwnership|getProjectOwnership|getUserId",
54
- "description": "API routes accessing user data must verify ownership",
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-hardcoded-secrets",
59
- "filePattern": "**/*.ts",
60
- "pattern": "AUTH_SECRET|V0_API_KEY|GITHUB_TOKEN|DATABASE_URL",
61
- "description": "Secrets must not be hardcoded (use environment variables)"
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-server-actions",
65
- "filePattern": "app/**/*.ts",
66
- "pattern": "fetch\\(.*process\\.env\\.",
67
- "description": "Server-side API calls should use server actions, not client-side fetch with env vars"
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 and log errors (not empty catch blocks)"
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-any-type",
101
- "filePattern": "**/*.ts",
102
- "pattern": ":\\s*any(?![a-zA-Z])",
103
- "description": "Avoid 'any' type (use proper TypeScript types)"
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": "use-next-link",
100
+ "id": "no-useeffect-commerce-fetch",
113
101
  "filePattern": "components/**/*.tsx",
114
- "pattern": "<a\\s+href",
115
- "description": "Use next/link Link component instead of <a> tag"
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-25"
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({ limit: 20 }),
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.id}`}>
43
- <Image src={product.thumbnail} alt={product.title} width={300} height={300} />
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-25"
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 (do NOT edit manually)
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-25"
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. `@meduzajs/js-sdk`, `@shopify/api`) | Backend is swappable via adapters | Vendor lock-in; migration requires rewrite |
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 (`@meduzajs/js-sdk`, `@shopify/api`, etc.)?
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?