@thorprovider/create-thor-app 4.0.0 → 4.1.0

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 (47) hide show
  1. package/README.md +31 -68
  2. package/dist/index.js +158 -629
  3. package/package.json +1 -1
  4. package/templates/default/.agents/AGENTS.md +27 -0
  5. package/templates/default/.env.example +12 -33
  6. package/templates/default/.eslintrc.json +20 -27
  7. package/templates/default/README.md +60 -119
  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 +45 -113
  17. package/templates/default/components/providers/app-providers.tsx +19 -68
  18. package/templates/default/components/providers/cart-provider.tsx +155 -0
  19. package/templates/default/components/providers/commerce-provider.tsx +34 -0
  20. package/templates/default/components/providers/region-provider.tsx +115 -0
  21. package/templates/default/docs/README.md +52 -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 +44 -42
  26. package/templates/default/docs/types.md +105 -1024
  27. package/templates/default/lib/commerce.ts +52 -135
  28. package/templates/default/lib/env.ts +68 -94
  29. package/templates/default/lib/utils.ts +18 -0
  30. package/templates/default/next.config.ts +7 -0
  31. package/templates/default/package.json +2 -8
  32. package/templates/default/registry.json +6 -0
  33. package/templates/default/styles/tokens.css +81 -0
  34. package/templates/default/components/providers/navigation-provider.tsx +0 -37
  35. package/templates/default/config/site.config.ts +0 -156
  36. package/templates/default/docs/components.md +0 -282
  37. package/templates/default/docs/dependencies.md +0 -61
  38. package/templates/default/lib/auth-context.tsx +0 -213
  39. package/templates/default/lib/cart-provider.tsx +0 -53
  40. package/templates/default/lib/commerce-provider.tsx +0 -48
  41. package/templates/default/lib/region-detection.ts +0 -73
  42. package/templates/default/lib/region-provider.tsx +0 -53
  43. package/templates/default/lib/regions-config.ts +0 -48
  44. package/templates/default/lib/storefront-config.ts +0 -54
  45. package/templates/default/next.config.mjs +0 -51
  46. package/templates/default/proxy.ts +0 -155
  47. package/templates/default/scripts/generate-regions-config.ts +0 -498
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
@@ -83,10 +85,7 @@ yarn create:app --name my-store \
83
85
  yarn create:app --name my-store \
84
86
  --commerce-provider medusa \
85
87
  --commerce-api-url https://my-backend.com \
86
- --commerce-api-key pk_live_xxx \
87
- --preset electro \
88
- --site-url https://my-store.com \
89
- --generate-regions
88
+ --commerce-api-key pk_live_xxx
90
89
 
91
90
  # With backend configuration
92
91
  yarn create:app --name my-store \
@@ -94,11 +93,6 @@ yarn create:app --name my-store \
94
93
  --commerce-api-url http://localhost:9000 \
95
94
  --commerce-api-key pk_abc123
96
95
 
97
- # With site configuration
98
- yarn create:app --name my-store \
99
- --preset electro \
100
- --site-url https://my-store.com
101
-
102
96
  # Custom output directory
103
97
  yarn create:app --name my-store --output /path/to/projects/my-store
104
98
  ```
@@ -110,15 +104,11 @@ When run outside the monorepo with `npx`, uses the pre-bundled template:
110
104
  npx @thorprovider/create-thor-app my-store
111
105
  ```
112
106
 
107
+ If you do not pass backend flags, the generated app starts in mock mode by default.
108
+
113
109
  **Differences from monorepo mode**:
114
110
  - Template is frozen at build time (versions pre-baked into `templates/default/package.json`)
115
111
  - No live dependency resolution — uses versions from the last build
116
- - `scripts/generate-regions-config.ts` is bundled in the standalone template
117
-
118
- **Environment** (for standalone):
119
- ```bash
120
- export NODE_AUTH_TOKEN=ghp_xxxxx # For GitHub Packages .npmrc
121
- ```
122
112
 
123
113
  ---
124
114
 
@@ -128,12 +118,9 @@ export NODE_AUTH_TOKEN=ghp_xxxxx # For GitHub Packages .npmrc
128
118
  |------|-------------|---------|
129
119
  | `--name <name>` | Project name (kebab-case) | Prompt if missing |
130
120
  | `-o, --output <dir>` | Output directory | `./<name>` |
131
- | `--commerce-provider <p>` | Commerce backend (`medusa`, `shopify`) → `.env` | `medusa` |
132
- | `--commerce-api-url <url>` | Backend API URL → `.env` | `http://localhost:9000` |
133
- | `--commerce-api-key <key>` | Publishable API key → `.env` | placeholder |
134
- | `--preset <preset>` | Visual preset → `site.config.ts` | `electro` |
135
- | `--site-url <url>` | Public site URL → `site.config.ts` | `https://example.com` |
136
- | `--generate-regions` | Run region generation from backend after install | `false` |
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 |
137
124
  | `--skip-git` | Skip git initialization | `false` |
138
125
  | `--skip-install` | Skip yarn install | `false` |
139
126
  | `--skip-remote` | Skip GitHub remote repo creation | `false` |
@@ -178,8 +165,13 @@ Next steps:
178
165
 
179
166
  — or —
180
167
 
181
- 1. Configure your backend:
182
- 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
183
175
 
184
176
  2. Add GitHub Actions secrets: ← (only when Vercel link succeeded)
185
177
  https://github.com/<org>/my-store/settings/secrets/actions
@@ -200,15 +192,12 @@ Next steps:
200
192
  **Generated structure**:
201
193
  ```
202
194
  projects/my-store/
203
- ├── .env # Backend config (copy from .env.example)
204
- ├── .npmrc # GitHub Packages auth (included)
195
+ ├── .env # Commerce config (mock by default, live backend optional)
205
196
  ├── .agents/
206
197
  │ ├── AGENTS.md # Entry point for AI agents (V0, Claude Code, OpenCode)
207
198
  │ ├── context/ # Architecture, types, API, patterns, rules
208
199
  │ │ ├── architecture.md
209
200
  │ │ ├── project-structure.md
210
- │ │ ├── dependencies.md
211
- │ │ ├── components.md
212
201
  │ │ ├── types.md
213
202
  │ │ ├── commerce-api.md
214
203
  │ │ ├── patterns.md
@@ -228,8 +217,8 @@ projects/my-store/
228
217
  ├── package.json # @thorprovider/my-store, updated deps
229
218
  ├── app/ # Next.js 16 app directory
230
219
  ├── components/ # UI components
231
- ├── lib/ # Commerce provider, config, utilities
232
- ├── scripts/ # generate-regions-config.ts (bundled)
220
+ ├── lib/ # Commerce config, env, utilities
221
+ ├── styles/ # Theme tokens
233
222
  └── ...
234
223
  ```
235
224
 
@@ -242,13 +231,8 @@ projects/my-store/
242
231
  - **Name**: `@thorprovider/<name>`
243
232
  - **Dependencies**: All `workspace:*` refs → `^X.Y.Z` (pre-baked versions)
244
233
  - **Scripts configured**:
245
- - `prebuild` / `predev`: Runs region generation
246
234
  - `dev`, `build`, `start`: Next.js commands
247
- - `generate:regions`: Region config generator
248
-
249
- ### .npmrc
250
-
251
- GitHub Packages registry config. Uses `NODE_AUTH_TOKEN` ENV for authentication.
235
+ - `type-check`: TypeScript validation
252
236
 
253
237
  ### .agents/
254
238
 
@@ -264,7 +248,10 @@ Use `--no-context` to skip generation.
264
248
 
265
249
  ### .env
266
250
 
267
- 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
268
255
 
269
256
  ### .vercel/project.json (conditional)
270
257
 
@@ -278,7 +265,6 @@ Required GitHub Actions secrets (printed during scaffolding):
278
265
  - `VERCEL_TOKEN` — Vercel Access Token
279
266
  - `VERCEL_ORG_ID` — From `.vercel/project.json`
280
267
  - `VERCEL_PROJECT_ID` — From `.vercel/project.json`
281
- - `NODE_AUTH_TOKEN` — GitHub PAT with `read:packages` (for `@thorprovider/*`)
282
268
 
283
269
  ---
284
270
 
@@ -322,11 +308,10 @@ yarn install
322
308
  ### Standalone usage (from outside monorepo)
323
309
 
324
310
  ```bash
325
- # Requires NODE_AUTH_TOKEN set
326
311
  npx @thorprovider/create-thor-app my-store
327
312
 
328
313
  cd my-store
329
- # Update .env with backend URL
314
+ # Optional: update .env with live backend settings, or keep mock mode
330
315
  yarn dev
331
316
  ```
332
317
 
@@ -364,27 +349,6 @@ yarn dev
364
349
 
365
350
  **Workaround**: Use `--skip-vercel` to skip, or set `VERCEL_TOKEN` and try again. Generate a token at https://vercel.com/account/tokens (Full Account scope).
366
351
 
367
- ### "Region generation failed"
368
-
369
- **Cause**: `--generate-regions` could not connect to the backend (timeout, wrong URL, wrong API key).
370
-
371
- **Behavior**: The scaffold does **not** fail. A fallback English-only `regions-config.ts` is generated automatically.
372
-
373
- **Fix**: Verify credentials in `.env`, then run:
374
- ```bash
375
- cd projects/my-store
376
- yarn generate:regions
377
- ```
378
-
379
- ### "`--generate-regions` skipped: requires dependencies"
380
-
381
- **Cause**: `--generate-regions` was used together with `--skip-install`.
382
-
383
- **Fix**: Install dependencies first, then run region generation manually:
384
- ```bash
385
- yarn install && yarn generate:regions
386
- ```
387
-
388
352
  ### "yarn install failed — run it manually"
389
353
 
390
354
  **Cause**: Missing dependencies or network issues.
@@ -458,10 +422,9 @@ The package is structured for maintainability:
458
422
  | `src/helpers/vercel.ts` | Vercel project creation via REST API |
459
423
  | `src/helpers/prompts.ts` | Shared TTY-aware interactive prompts |
460
424
  | `src/helpers/install.ts` | Yarn install wrapper |
461
- | `src/helpers/env.ts` | .env + .npmrc creation (accepts overrides for backend flags) |
462
- | `src/helpers/site-config.ts` | Patches `config/site.config.ts` with `--preset` / `--site-url` |
425
+ | `src/helpers/env.ts` | .env creation (accepts backend overrides) |
463
426
  | `src/helpers/agents-dir.ts` | .agents/ directory generation (AGENTS.md + context/ + skills/) |
464
- | `tsup.config.ts` | Build config + template bundling hook (copies regions script) |
427
+ | `tsup.config.ts` | Build config + template bundling hook |
465
428
 
466
429
  ### Dual-mode detection
467
430
 
@@ -473,15 +436,15 @@ The package is structured for maintainability:
473
436
 
474
437
  ## Publishing
475
438
 
476
- The package is published to GitHub Packages with `publishConfig.access = "restricted"`:
439
+ This package is published publicly to npm through the monorepo Changesets workflow:
477
440
 
478
441
  ```bash
479
442
  yarn changeset
480
- yarn version-packages
481
- yarn ci:publish
443
+ # open and merge your PR to main
444
+ # CI versions and publishes on push to main
482
445
  ```
483
446
 
484
- 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.
485
448
 
486
449
  ---
487
450