@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.
- package/README.md +31 -68
- package/dist/index.js +158 -629
- package/package.json +1 -1
- package/templates/default/.agents/AGENTS.md +27 -0
- package/templates/default/.env.example +12 -33
- package/templates/default/.eslintrc.json +20 -27
- package/templates/default/README.md +60 -119
- package/templates/default/ai-validator.json +47 -29
- package/templates/default/app/api/revalidate/route.ts +27 -36
- package/templates/default/app/backend-unavailable/page.tsx +3 -7
- package/templates/default/app/error.tsx +1 -2
- package/templates/default/app/global-error.tsx +3 -3
- package/templates/default/app/globals.css +1 -71
- package/templates/default/app/layout.tsx +16 -38
- package/templates/default/app/not-found.tsx +1 -1
- package/templates/default/app/page.tsx +45 -113
- package/templates/default/components/providers/app-providers.tsx +19 -68
- package/templates/default/components/providers/cart-provider.tsx +155 -0
- package/templates/default/components/providers/commerce-provider.tsx +34 -0
- package/templates/default/components/providers/region-provider.tsx +115 -0
- package/templates/default/docs/README.md +52 -37
- package/templates/default/docs/commerce-api.md +58 -125
- package/templates/default/docs/patterns.md +128 -67
- package/templates/default/docs/project-structure.md +58 -50
- package/templates/default/docs/rules.md +44 -42
- package/templates/default/docs/types.md +105 -1024
- package/templates/default/lib/commerce.ts +52 -135
- package/templates/default/lib/env.ts +68 -94
- package/templates/default/lib/utils.ts +18 -0
- package/templates/default/next.config.ts +7 -0
- package/templates/default/package.json +2 -8
- package/templates/default/registry.json +6 -0
- package/templates/default/styles/tokens.css +81 -0
- package/templates/default/components/providers/navigation-provider.tsx +0 -37
- package/templates/default/config/site.config.ts +0 -156
- package/templates/default/docs/components.md +0 -282
- package/templates/default/docs/dependencies.md +0 -61
- package/templates/default/lib/auth-context.tsx +0 -213
- package/templates/default/lib/cart-provider.tsx +0 -53
- package/templates/default/lib/commerce-provider.tsx +0 -48
- package/templates/default/lib/region-detection.ts +0 -73
- package/templates/default/lib/region-provider.tsx +0 -53
- package/templates/default/lib/regions-config.ts +0 -48
- package/templates/default/lib/storefront-config.ts +0 -54
- package/templates/default/next.config.mjs +0 -51
- package/templates/default/proxy.ts +0 -155
- 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-
|
|
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` | `
|
|
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.
|
|
182
|
-
|
|
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 #
|
|
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
|
|
232
|
-
├──
|
|
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
|
-
- `
|
|
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`.
|
|
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
|
-
#
|
|
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
|
|
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
|
|
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
|
-
|
|
439
|
+
This package is published publicly to npm through the monorepo Changesets workflow:
|
|
477
440
|
|
|
478
441
|
```bash
|
|
479
442
|
yarn changeset
|
|
480
|
-
|
|
481
|
-
|
|
443
|
+
# open and merge your PR to main
|
|
444
|
+
# CI versions and publishes on push to main
|
|
482
445
|
```
|
|
483
446
|
|
|
484
|
-
|
|
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
|
|