@thorprovider/create-thor-app 4.0.1 → 4.1.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 +27 -13
- package/package.json +1 -1
- package/templates/default/.agents/AGENTS.md +6 -1
- package/templates/default/.env.example +6 -5
- package/templates/default/README.md +13 -1
- package/templates/default/docs/README.md +6 -0
- package/templates/default/docs/commerce-api.md +9 -0
- package/templates/default/docs/patterns.md +10 -0
- package/templates/default/package.json +3 -2
package/README.md
CHANGED
|
@@ -1,13 +1,15 @@
|
|
|
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-
|
|
4
|
+
lastReviewed: "2026-05-01"
|
|
5
5
|
---
|
|
6
6
|
|
|
7
7
|
# create-thor-app
|
|
8
8
|
|
|
9
9
|
CLI scaffolding tool to generate a new Thor Commerce application from the `@thorprovider/core` template.
|
|
10
10
|
|
|
11
|
+
The generated storefront is **mock-first by default**: if no live backend config is supplied, the app starts with the `mock` provider so layout and preview work can begin immediately.
|
|
12
|
+
|
|
11
13
|
Supports **dual-mode** operation:
|
|
12
14
|
- **Monorepo mode**: Copy live `packages/core`, run from within the monorepo
|
|
13
15
|
- **Standalone mode**: Use bundled template, run via `npx` from anywhere
|
|
@@ -102,6 +104,8 @@ When run outside the monorepo with `npx`, uses the pre-bundled template:
|
|
|
102
104
|
npx @thorprovider/create-thor-app my-store
|
|
103
105
|
```
|
|
104
106
|
|
|
107
|
+
If you do not pass backend flags, the generated app starts in mock mode by default.
|
|
108
|
+
|
|
105
109
|
**Differences from monorepo mode**:
|
|
106
110
|
- Template is frozen at build time (versions pre-baked into `templates/default/package.json`)
|
|
107
111
|
- No live dependency resolution — uses versions from the last build
|
|
@@ -114,9 +118,9 @@ npx @thorprovider/create-thor-app my-store
|
|
|
114
118
|
|------|-------------|---------|
|
|
115
119
|
| `--name <name>` | Project name (kebab-case) | Prompt if missing |
|
|
116
120
|
| `-o, --output <dir>` | Output directory | `./<name>` |
|
|
117
|
-
| `--commerce-provider <p>` | Commerce backend (`medusa`, `shopify`) → `.env` | `
|
|
118
|
-
| `--commerce-api-url <url>` | Backend API URL → `.env` | `http://localhost:9000` |
|
|
119
|
-
| `--commerce-api-key <key>` | Publishable API key → `.env` | placeholder |
|
|
121
|
+
| `--commerce-provider <p>` | Commerce backend (`mock`, `medusa`, `shopify`) → `.env` | `mock` |
|
|
122
|
+
| `--commerce-api-url <url>` | Backend API URL → `.env` (required only for real backends) | `http://localhost:9000` |
|
|
123
|
+
| `--commerce-api-key <key>` | Publishable API key → `.env` (required only for real backends) | placeholder |
|
|
120
124
|
| `--skip-git` | Skip git initialization | `false` |
|
|
121
125
|
| `--skip-install` | Skip yarn install | `false` |
|
|
122
126
|
| `--skip-remote` | Skip GitHub remote repo creation | `false` |
|
|
@@ -161,8 +165,13 @@ Next steps:
|
|
|
161
165
|
|
|
162
166
|
— or —
|
|
163
167
|
|
|
164
|
-
1.
|
|
165
|
-
|
|
168
|
+
1. Start in mock mode immediately:
|
|
169
|
+
`projects/my-store/.env` already defaults to `NEXT_PUBLIC_COMMERCE_PROVIDER=mock`
|
|
170
|
+
|
|
171
|
+
— or —
|
|
172
|
+
|
|
173
|
+
1. Configure your live backend:
|
|
174
|
+
Edit `projects/my-store/.env` with your commerce backend URL and API key
|
|
166
175
|
|
|
167
176
|
2. Add GitHub Actions secrets: ← (only when Vercel link succeeded)
|
|
168
177
|
https://github.com/<org>/my-store/settings/secrets/actions
|
|
@@ -183,7 +192,7 @@ Next steps:
|
|
|
183
192
|
**Generated structure**:
|
|
184
193
|
```
|
|
185
194
|
projects/my-store/
|
|
186
|
-
├── .env #
|
|
195
|
+
├── .env # Commerce config (mock by default, live backend optional)
|
|
187
196
|
├── .agents/
|
|
188
197
|
│ ├── AGENTS.md # Entry point for AI agents (V0, Claude Code, OpenCode)
|
|
189
198
|
│ ├── context/ # Architecture, types, API, patterns, rules
|
|
@@ -239,7 +248,10 @@ Use `--no-context` to skip generation.
|
|
|
239
248
|
|
|
240
249
|
### .env
|
|
241
250
|
|
|
242
|
-
Copied from `.env.example`.
|
|
251
|
+
Copied from `.env.example`.
|
|
252
|
+
|
|
253
|
+
- Default: starts in `mock` mode with no backend required
|
|
254
|
+
- Optional: add real provider + backend URL + publishable key to use live commerce data immediately
|
|
243
255
|
|
|
244
256
|
### .vercel/project.json (conditional)
|
|
245
257
|
|
|
@@ -299,7 +311,7 @@ yarn install
|
|
|
299
311
|
npx @thorprovider/create-thor-app my-store
|
|
300
312
|
|
|
301
313
|
cd my-store
|
|
302
|
-
#
|
|
314
|
+
# Optional: update .env with live backend settings, or keep mock mode
|
|
303
315
|
yarn dev
|
|
304
316
|
```
|
|
305
317
|
|
|
@@ -424,15 +436,17 @@ The package is structured for maintainability:
|
|
|
424
436
|
|
|
425
437
|
## Publishing
|
|
426
438
|
|
|
427
|
-
|
|
439
|
+
This package is published publicly to npm through the monorepo Changesets workflow:
|
|
428
440
|
|
|
429
441
|
```bash
|
|
430
442
|
yarn changeset
|
|
431
|
-
|
|
432
|
-
|
|
443
|
+
# open and merge your PR to main
|
|
444
|
+
# CI versions and publishes on push to main
|
|
433
445
|
```
|
|
434
446
|
|
|
435
|
-
|
|
447
|
+
Include `@thorprovider/create-thor-app` in a changeset whenever you change the CLI, its bundled template, or any publishable behavior consumers depend on.
|
|
448
|
+
|
|
449
|
+
When a release includes `@thorprovider/types` or `@thorprovider/adapters`, release automation also auto-bumps `@thorprovider/create-thor-app` so the published starter template keeps those dependency versions aligned.
|
|
436
450
|
|
|
437
451
|
---
|
|
438
452
|
|
package/package.json
CHANGED
|
@@ -19,9 +19,14 @@ ALWAYS import from @thorprovider/types — NEVER define Product, Cart, Collectio
|
|
|
19
19
|
- useRegion() — @/components/providers/region-provider
|
|
20
20
|
- useCommerce() — @/components/providers/commerce-provider
|
|
21
21
|
|
|
22
|
+
## Runtime
|
|
23
|
+
- Default to mock mode when backend env is missing
|
|
24
|
+
- Real provider + URL + API key => live backend immediately
|
|
25
|
+
- Same commerce/useCart/useRegion APIs in both modes
|
|
26
|
+
|
|
22
27
|
## Stack
|
|
23
28
|
Next.js 16, React 19, TS strict, Tailwind 4, shadcn/ui.
|
|
24
29
|
Server Components default. 'use client' only for interactivity.
|
|
25
30
|
|
|
26
31
|
## Docs
|
|
27
|
-
docs/types.md (types), docs/patterns.md (examples).
|
|
32
|
+
docs/types.md (types), docs/patterns.md (examples).
|
|
@@ -5,15 +5,16 @@
|
|
|
5
5
|
# ============================================================================
|
|
6
6
|
|
|
7
7
|
# ---------------------------------------------------------------------------
|
|
8
|
-
# Commerce Backend (
|
|
8
|
+
# Commerce Backend (optional)
|
|
9
9
|
# ---------------------------------------------------------------------------
|
|
10
|
-
# Which commerce platform to use: medusa | shopify | bigcommerce | custom
|
|
11
|
-
|
|
10
|
+
# Which commerce platform to use: mock | medusa | shopify | bigcommerce | custom
|
|
11
|
+
# Use `mock` to design/layout the storefront before a real backend is connected.
|
|
12
|
+
NEXT_PUBLIC_COMMERCE_PROVIDER=mock
|
|
12
13
|
|
|
13
|
-
# Your commerce backend API URL
|
|
14
|
+
# Your commerce backend API URL (required for real backends, ignored in mock mode)
|
|
14
15
|
NEXT_PUBLIC_COMMERCE_API_URL=http://localhost:9000
|
|
15
16
|
|
|
16
|
-
# Publishable API key for your commerce backend
|
|
17
|
+
# Publishable API key for your commerce backend (required for real backends, ignored in mock mode)
|
|
17
18
|
NEXT_PUBLIC_COMMERCE_API_KEY=your-publishable-api-key
|
|
18
19
|
|
|
19
20
|
# ---------------------------------------------------------------------------
|
|
@@ -30,12 +30,23 @@ yarn dev
|
|
|
30
30
|
# → http://localhost:3000
|
|
31
31
|
```
|
|
32
32
|
|
|
33
|
-
|
|
33
|
+
Default runtime:
|
|
34
|
+
```
|
|
35
|
+
NEXT_PUBLIC_COMMERCE_PROVIDER=mock
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
Live backend environment (only required when using a real provider):
|
|
34
39
|
```
|
|
35
40
|
NEXT_PUBLIC_COMMERCE_API_URL=https://your-backend.com
|
|
36
41
|
NEXT_PUBLIC_COMMERCE_API_KEY=pk_live_xxx
|
|
37
42
|
```
|
|
38
43
|
|
|
44
|
+
### Runtime modes
|
|
45
|
+
|
|
46
|
+
- `mock` or missing live-backend env vars → storefront uses fixture-backed mock commerce data
|
|
47
|
+
- real provider + API URL + API key → storefront uses the live backend immediately
|
|
48
|
+
- switching config later should not require rewriting app code that calls `commerce.*`, `useCart()`, or `useRegion()`
|
|
49
|
+
|
|
39
50
|
## Development with V0
|
|
40
51
|
|
|
41
52
|
1. Push this repo to GitHub
|
|
@@ -55,6 +66,7 @@ NEXT_PUBLIC_COMMERCE_API_KEY=pk_live_xxx
|
|
|
55
66
|
## What's Pre-Configured
|
|
56
67
|
|
|
57
68
|
- Commerce singleton with adapter-based backend access (retry built-in)
|
|
69
|
+
- Mock-first runtime that works without a live backend
|
|
58
70
|
- Shopping cart (persistent, backend-synced)
|
|
59
71
|
- Authentication (JWT)
|
|
60
72
|
- Dark mode + CSS token theming + backend-driven accent color
|
|
@@ -8,6 +8,12 @@ lastReviewed: "2026-05-01"
|
|
|
8
8
|
|
|
9
9
|
Next.js 16 storefront scaffold for V0 AI code generation. Two npm deps: `@thorprovider/types` + `@thorprovider/adapters`.
|
|
10
10
|
|
|
11
|
+
## Runtime modes
|
|
12
|
+
|
|
13
|
+
- **Mock-first**: the template defaults to `mock` so previews work even before a backend exists.
|
|
14
|
+
- **Live immediately**: if real backend env vars are present, the same template runtime uses the live provider immediately.
|
|
15
|
+
- **Same app code**: pages/components should keep using `commerce`, `useCart()`, `useRegion()`, and `useCommerce()` without provider-specific branching.
|
|
16
|
+
|
|
11
17
|
## How It Works
|
|
12
18
|
|
|
13
19
|
V0 generates feature code (pages, components) on top of this frozen infrastructure. The template provides:
|
|
@@ -12,6 +12,13 @@ All backend access goes through the `commerce` singleton from `@/lib/commerce`.
|
|
|
12
12
|
import { commerce } from '@/lib/commerce';
|
|
13
13
|
```
|
|
14
14
|
|
|
15
|
+
## Runtime Modes
|
|
16
|
+
|
|
17
|
+
- `mock` provider, or missing real-backend env vars → `commerce` uses a fixture-backed mock provider for layout/preview work.
|
|
18
|
+
- Real provider + `NEXT_PUBLIC_COMMERCE_API_URL` + `NEXT_PUBLIC_COMMERCE_API_KEY` → `commerce` uses the live backend immediately.
|
|
19
|
+
- The `commerce.*` API stays the same in both modes. Write app code against the shared interface instead of branching on provider.
|
|
20
|
+
- If backend config is added later, products, categories, region, cart, checkout, and auth flows switch to the live provider without changing call sites.
|
|
21
|
+
|
|
15
22
|
---
|
|
16
23
|
|
|
17
24
|
## Products
|
|
@@ -171,6 +178,8 @@ try {
|
|
|
171
178
|
}
|
|
172
179
|
```
|
|
173
180
|
|
|
181
|
+
In `mock` mode there is no backend network dependency, so preview/design work should continue without live-backend health checks.
|
|
182
|
+
|
|
174
183
|
---
|
|
175
184
|
|
|
176
185
|
## Optional Methods
|
|
@@ -6,6 +6,14 @@ lastReviewed: "2026-05-01"
|
|
|
6
6
|
|
|
7
7
|
# Patterns (Code Templates)
|
|
8
8
|
|
|
9
|
+
## Runtime Invariant
|
|
10
|
+
|
|
11
|
+
Write storefront code against `commerce`, `useCart()`, `useRegion()`, and `useCommerce()` directly.
|
|
12
|
+
|
|
13
|
+
- Do **not** create separate mock-vs-live component trees for normal storefront UI.
|
|
14
|
+
- The same patterns should work in preview with mock data and later against a live backend.
|
|
15
|
+
- Provider transitions are handled by the infrastructure layer, not by per-component conditionals.
|
|
16
|
+
|
|
9
17
|
## 1. Server Page (Data Fetch)
|
|
10
18
|
|
|
11
19
|
```tsx
|
|
@@ -87,6 +95,7 @@ export function AddToCartButton({ variantId }: { variantId: string }) {
|
|
|
87
95
|
|
|
88
96
|
- Import `useCart` from `@/components/providers/cart-provider`.
|
|
89
97
|
- Cart methods: `addItem(variantId, quantity)`, `removeItem(lineItemId)`, `updateQuantity(lineItemId, qty)`, `clearCart()`.
|
|
98
|
+
- When the storefront switches from mock to live backend, `CartProvider` resets incompatible persisted cart state automatically.
|
|
90
99
|
|
|
91
100
|
---
|
|
92
101
|
|
|
@@ -114,6 +123,7 @@ export function CurrencySelector() {
|
|
|
114
123
|
```
|
|
115
124
|
|
|
116
125
|
- Import `useRegion` from `@/components/providers/region-provider`.
|
|
126
|
+
- When the provider changes between mock and live, `RegionProvider` clears stale persisted region state automatically.
|
|
117
127
|
|
|
118
128
|
---
|
|
119
129
|
|
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@thorprovider/core",
|
|
3
3
|
"version": "2.0.0",
|
|
4
|
+
"private": true,
|
|
4
5
|
"description": "Thor Commerce V0-native template. Lean storefront scaffold for V0 AI code generation.",
|
|
5
6
|
"scripts": {
|
|
6
7
|
"build": "next build",
|
|
@@ -10,8 +11,8 @@
|
|
|
10
11
|
"generate:agent-index": "node ../../scripts/generate-core-agents-index.cjs"
|
|
11
12
|
},
|
|
12
13
|
"dependencies": {
|
|
13
|
-
"@thorprovider/adapters": "^4.
|
|
14
|
-
"@thorprovider/types": "^3.
|
|
14
|
+
"@thorprovider/adapters": "^4.2.0",
|
|
15
|
+
"@thorprovider/types": "^3.2.0",
|
|
15
16
|
"clsx": "^2.1.1",
|
|
16
17
|
"next": "16.0.10",
|
|
17
18
|
"react": "19.2.0",
|