@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 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-04-29"
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` | `medusa` |
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. Configure your backend:
165
- Edit projects/my-store/.env with your commerce backend URL and API key
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 # Backend config (copy from .env.example)
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`. Update with your Medusa backend URL before running `yarn dev`.
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
- # Update .env with backend URL
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
- The package is published to GitHub Packages with `publishConfig.access = "restricted"`:
439
+ This package is published publicly to npm through the monorepo Changesets workflow:
428
440
 
429
441
  ```bash
430
442
  yarn changeset
431
- yarn version-packages
432
- yarn ci:publish
443
+ # open and merge your PR to main
444
+ # CI versions and publishes on push to main
433
445
  ```
434
446
 
435
- Only include `@thorprovider/create-thor-app` in changesets if publishing this package alone.
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@thorprovider/create-thor-app",
3
- "version": "4.0.1",
3
+ "version": "4.1.1",
4
4
  "description": "CLI to scaffold a new Thor Commerce V0-native application",
5
5
  "type": "module",
6
6
  "bin": "./dist/index.js",
@@ -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 (required)
8
+ # Commerce Backend (optional)
9
9
  # ---------------------------------------------------------------------------
10
- # Which commerce platform to use: medusa | shopify | bigcommerce | custom
11
- NEXT_PUBLIC_COMMERCE_PROVIDER=medusa
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
- Required environment:
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.0.0",
14
- "@thorprovider/types": "^3.0.0",
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",