@thorprovider/create-thor-app 2.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 (42) hide show
  1. package/README.md +470 -0
  2. package/dist/index.js +1054 -0
  3. package/package.json +46 -0
  4. package/templates/default/.env.example +56 -0
  5. package/templates/default/.eslintrc.json +43 -0
  6. package/templates/default/README.md +151 -0
  7. package/templates/default/app/api/revalidate/route.ts +64 -0
  8. package/templates/default/app/backend-unavailable/page.tsx +85 -0
  9. package/templates/default/app/error.tsx +58 -0
  10. package/templates/default/app/global-error.tsx +208 -0
  11. package/templates/default/app/globals.css +125 -0
  12. package/templates/default/app/layout.tsx +50 -0
  13. package/templates/default/app/not-found.tsx +31 -0
  14. package/templates/default/app/page.tsx +124 -0
  15. package/templates/default/components/providers/app-providers.tsx +77 -0
  16. package/templates/default/components/providers/navigation-provider.tsx +37 -0
  17. package/templates/default/config/site.config.ts +156 -0
  18. package/templates/default/docs/README.md +46 -0
  19. package/templates/default/docs/commerce-api.md +243 -0
  20. package/templates/default/docs/components.md +276 -0
  21. package/templates/default/docs/dependencies.md +53 -0
  22. package/templates/default/docs/patterns.md +100 -0
  23. package/templates/default/docs/project-structure.md +53 -0
  24. package/templates/default/docs/rules.md +51 -0
  25. package/templates/default/docs/types.md +329 -0
  26. package/templates/default/lib/auth-context.tsx +213 -0
  27. package/templates/default/lib/cart-provider.tsx +53 -0
  28. package/templates/default/lib/commerce-provider.tsx +48 -0
  29. package/templates/default/lib/commerce.ts +165 -0
  30. package/templates/default/lib/env.ts +147 -0
  31. package/templates/default/lib/region-detection.ts +80 -0
  32. package/templates/default/lib/region-provider.tsx +53 -0
  33. package/templates/default/lib/regions-config.ts +48 -0
  34. package/templates/default/lib/storefront-config.ts +54 -0
  35. package/templates/default/lib/utils.ts +10 -0
  36. package/templates/default/next-env.d.ts +6 -0
  37. package/templates/default/next.config.mjs +51 -0
  38. package/templates/default/package.json +42 -0
  39. package/templates/default/postcss.config.mjs +8 -0
  40. package/templates/default/proxy.ts +155 -0
  41. package/templates/default/scripts/generate-regions-config.ts +498 -0
  42. package/templates/default/tsconfig.json +43 -0
package/README.md ADDED
@@ -0,0 +1,470 @@
1
+ # create-thor-app
2
+
3
+ CLI scaffolding tool to generate a new Thor Commerce application from the `@thorprovider/core` template.
4
+
5
+ Supports **dual-mode** operation:
6
+ - **Monorepo mode**: Copy live `packages/core`, run from within the monorepo
7
+ - **Standalone mode**: Use bundled template, run via `npx` from anywhere
8
+
9
+ ---
10
+
11
+ ## Installation
12
+
13
+ ### GitHub Packages (Recommended for Internal Use)
14
+
15
+ This package is published to GitHub Packages with restricted access (`@thorprovider` scope).
16
+
17
+ **Setup** (one-time):
18
+ 1. Create a GitHub personal access token (PAT) with `read:packages` scope
19
+ 2. Add to your shell profile (`~/.bashrc` / `~/.zshrc`):
20
+ ```bash
21
+ export NODE_AUTH_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
22
+ ```
23
+ 3. Install globally (optional):
24
+ ```bash
25
+ npm install -g @thorprovider/create-thor-app
26
+ ```
27
+
28
+ ### From Monorepo
29
+
30
+ Run directly from the monorepo (no publish required):
31
+ ```bash
32
+ yarn create:app --name my-store
33
+ ```
34
+
35
+ ---
36
+
37
+ ## Usage
38
+
39
+ ### Monorepo Mode
40
+
41
+ When run from within the Thor Commerce monorepo, the CLI auto-detects and:
42
+ - Copies live `packages/core` template
43
+ - Resolves `workspace:*` deps to live monorepo versions at build time
44
+ - Places the new project in `projects/<name>/`
45
+
46
+ **Setup Git environment** (optional, for remote repo creation):
47
+ ```bash
48
+ # In the monorepo root .env
49
+ GITHUB_TOKEN=ghp_xxxxx
50
+ GITHUB_ORG=myorg # (optional — defaults to user)
51
+ GITHUB_REPO_VISIBILITY=public # (default: private)
52
+ GIT_AUTHOR_NAME=Your Name # (default: "Thor Commerce")
53
+ GIT_AUTHOR_EMAIL=you@example.com
54
+ ```
55
+
56
+ **Setup Vercel environment** (optional, for Vercel project linking):
57
+ ```bash
58
+ # In the monorepo root .env
59
+ VERCEL_TOKEN=your_vercel_token
60
+ VERCEL_TEAM_SLUG=my-team # (optional — defaults to personal account)
61
+ ```
62
+
63
+ **Examples**:
64
+ ```bash
65
+ # Interactive prompt
66
+ yarn create:app
67
+
68
+ # With name
69
+ yarn create:app --name my-store
70
+
71
+ # Full options
72
+ yarn create:app --name my-store \
73
+ --skip-git \
74
+ --skip-install \
75
+ --skip-remote \
76
+ --skip-vercel \
77
+ --skip-v0-context
78
+
79
+ # Full backend setup in one command
80
+ yarn create:app --name my-store \
81
+ --commerce-provider medusa \
82
+ --commerce-api-url https://my-backend.com \
83
+ --commerce-api-key pk_live_xxx \
84
+ --preset electro \
85
+ --site-url https://my-store.com \
86
+ --generate-regions
87
+
88
+ # With backend configuration
89
+ yarn create:app --name my-store \
90
+ --commerce-provider medusa \
91
+ --commerce-api-url http://localhost:9000 \
92
+ --commerce-api-key pk_abc123
93
+
94
+ # With site configuration
95
+ yarn create:app --name my-store \
96
+ --preset electro \
97
+ --site-url https://my-store.com
98
+
99
+ # Custom output directory
100
+ yarn create:app --name my-store --output /path/to/projects/my-store
101
+ ```
102
+
103
+ ### Standalone Mode (npx)
104
+
105
+ When run outside the monorepo with `npx`, uses the pre-bundled template:
106
+ ```bash
107
+ npx @thorprovider/create-thor-app my-store
108
+ ```
109
+
110
+ **Differences from monorepo mode**:
111
+ - Template is frozen at build time (versions pre-baked into `templates/default/package.json`)
112
+ - No live dependency resolution — uses versions from the last build
113
+ - `scripts/generate-regions-config.ts` is bundled in the standalone template
114
+
115
+ **Environment** (for standalone):
116
+ ```bash
117
+ export NODE_AUTH_TOKEN=ghp_xxxxx # For GitHub Packages .npmrc
118
+ ```
119
+
120
+ ---
121
+
122
+ ## CLI Options
123
+
124
+ | Flag | Description | Default |
125
+ |------|-------------|---------|
126
+ | `--name <name>` | Project name (kebab-case) | Prompt if missing |
127
+ | `-o, --output <dir>` | Output directory | `./<name>` |
128
+ | `--commerce-provider <p>` | Commerce backend (`medusa`, `shopify`) → `.env` | `medusa` |
129
+ | `--commerce-api-url <url>` | Backend API URL → `.env` | `http://localhost:9000` |
130
+ | `--commerce-api-key <key>` | Publishable API key → `.env` | placeholder |
131
+ | `--preset <preset>` | Visual preset → `site.config.ts` | `electro` |
132
+ | `--site-url <url>` | Public site URL → `site.config.ts` | `https://example.com` |
133
+ | `--generate-regions` | Run region generation from backend after install | `false` |
134
+ | `--skip-git` | Skip git initialization | `false` |
135
+ | `--skip-install` | Skip yarn install | `false` |
136
+ | `--skip-remote` | Skip GitHub remote repo creation | `false` |
137
+ | `--skip-vercel` | Skip Vercel project linking | `false` |
138
+ | `--skip-v0-context` | Skip .v0-context.md generation | `false` |
139
+ | `-h, --help` | Show help | — |
140
+
141
+ > **Security note**: `--commerce-api-key` values appear in shell history.
142
+ > For sensitive keys, prefer editing `.env` manually after scaffolding.
143
+
144
+ ---
145
+
146
+ ## Interactive Prompts
147
+
148
+ When run with **no arguments**, prompts for project name:
149
+ ```bash
150
+ $ yarn create:app
151
+ ? Project name (kebab-case): _
152
+ ```
153
+
154
+ After scaffolding files, the CLI interactively asks (with TTY defaults):
155
+ ```bash
156
+ ? Create a GitHub remote repository? (Y/n): _
157
+ ? Link project to Vercel for automatic deployments? (y/N): _
158
+ ```
159
+
160
+ - In **non-interactive environments** (CI, piped stdin), these default to their respective flags (`Y` for GitHub remote, `N` for Vercel).
161
+ - Pass `--skip-remote` or `--skip-vercel` to suppress the prompts entirely.
162
+
163
+ ---
164
+
165
+ ## Output
166
+
167
+ After successful scaffolding, the CLI prints next steps:
168
+
169
+ ```
170
+ ✅ Project created successfully!
171
+
172
+ Next steps:
173
+
174
+ 1. Backend already configured (via CLI flags) ✓ ← (when --commerce-api-url + --commerce-api-key were used)
175
+
176
+ — or —
177
+
178
+ 1. Configure your backend:
179
+ Edit projects/my-store/.env with your commerce backend URL and API key
180
+
181
+ 2. Add GitHub Actions secrets: ← (only when Vercel link succeeded)
182
+ https://github.com/<org>/my-store/settings/secrets/actions
183
+
184
+ — or —
185
+
186
+ 2. Link to Vercel (when ready): ← (when Vercel was skipped)
187
+ cd projects/my-store && vercel link
188
+
189
+ 3. Connect to V0:
190
+ Open https://v0.dev → New project → Connect GitHub repo
191
+ Then paste .v0-context.md as the first message
192
+
193
+ 4. Start developing:
194
+ cd projects/my-store && yarn dev
195
+ ```
196
+
197
+ **Generated structure**:
198
+ ```
199
+ projects/my-store/
200
+ ├── .env # Backend config (copy from .env.example)
201
+ ├── .npmrc # GitHub Packages auth (included)
202
+ ├── .v0-context.md # 14 frozen architecture files for V0
203
+ ├── .vercel/
204
+ │ └── project.json # Vercel org/project IDs (when Vercel linked)
205
+ ├── .github/
206
+ │ └── workflows/
207
+ │ └── vercel-deploy.yml # CI/CD deploy workflow (when Vercel linked)
208
+ ├── package.json # @thorprovider/my-store, updated deps
209
+ ├── app/ # Next.js 16 app directory
210
+ ├── components/ # UI components
211
+ ├── lib/ # Commerce provider, config, utilities
212
+ ├── scripts/ # generate-regions-config.ts (bundled)
213
+ └── ...
214
+ ```
215
+
216
+ ---
217
+
218
+ ## What Gets Generated
219
+
220
+ ### package.json
221
+
222
+ - **Name**: `@thorprovider/<name>`
223
+ - **Dependencies**: All `workspace:*` refs → `^X.Y.Z` (pre-baked versions)
224
+ - **Scripts configured**:
225
+ - `prebuild` / `predev`: Runs region generation
226
+ - `dev`, `build`, `start`: Next.js commands
227
+ - `generate:regions`: Region config generator
228
+
229
+ ### .npmrc
230
+
231
+ GitHub Packages registry config. Uses `NODE_AUTH_TOKEN` ENV for authentication.
232
+
233
+ ### .v0-context.md
234
+
235
+ Contains 14 frozen architecture files (docs, lib, components, config) for V0 prompting. Paste this as the first message when setting up V0 to avoid re-implementing patterns.
236
+
237
+ ### .env
238
+
239
+ Copied from `.env.example`. Update with your Medusa backend URL before running `yarn dev`.
240
+
241
+ ### .vercel/project.json (conditional)
242
+
243
+ Created when Vercel linking succeeds. Contains `orgId` and `projectId` required by `vercel` CLI and the GitHub Actions workflow. Generated automatically — do not edit manually.
244
+
245
+ ### .github/workflows/vercel-deploy.yml (conditional)
246
+
247
+ Generated when Vercel linking succeeds. Deploys to Vercel on every push to `main` and posts preview URLs on pull requests.
248
+
249
+ Required GitHub Actions secrets (printed during scaffolding):
250
+ - `VERCEL_TOKEN` — Vercel Access Token
251
+ - `VERCEL_ORG_ID` — From `.vercel/project.json`
252
+ - `VERCEL_PROJECT_ID` — From `.vercel/project.json`
253
+ - `NODE_AUTH_TOKEN` — GitHub PAT with `read:packages` (for `@thorprovider/*`)
254
+
255
+ ---
256
+
257
+ ## Examples
258
+
259
+ ### Create a new storefront in monorepo
260
+
261
+ ```bash
262
+ cd thor-commerce
263
+ yarn create:app --name my-shop
264
+ cd projects/my-shop
265
+ yarn dev
266
+ ```
267
+
268
+ ### Scaffold + push to GitHub
269
+
270
+ ```bash
271
+ # In monorepo root, set .env
272
+ export GITHUB_TOKEN=ghp_xxxxx
273
+ export GITHUB_ORG=my-org
274
+
275
+ yarn create:app --name my-shop
276
+
277
+ # Verify the remote was created
278
+ cd projects/my-shop
279
+ git remote -v
280
+ ```
281
+
282
+ ### Create without git or install (for CI/CD)
283
+
284
+ ```bash
285
+ yarn create:app --name my-shop \
286
+ --skip-git \
287
+ --skip-install
288
+
289
+ cd projects/my-shop
290
+ # ... run custom setup (docker build, etc.)
291
+ yarn install
292
+ ```
293
+
294
+ ### Standalone usage (from outside monorepo)
295
+
296
+ ```bash
297
+ # Requires NODE_AUTH_TOKEN set
298
+ npx @thorprovider/create-thor-app my-store
299
+
300
+ cd my-store
301
+ # Update .env with backend URL
302
+ yarn dev
303
+ ```
304
+
305
+ ---
306
+
307
+ ## Troubleshooting
308
+
309
+ ### "Cannot find Thor Commerce monorepo"
310
+
311
+ **Cause**: Running from outside the monorepo without `npx` or without the bundled CLI.
312
+
313
+ **Fix**: Use `npx @thorprovider/create-thor-app` or run from within `thor-commerce/`.
314
+
315
+ ### "Directory already exists"
316
+
317
+ **Cause**: Output path already exists.
318
+
319
+ **Fix**: Choose a different `--name` or delete the existing directory.
320
+
321
+ ### "git init failed"
322
+
323
+ **Cause**: Git not installed or not in `$PATH`.
324
+
325
+ **Workaround**: Use `--skip-git` and initialize manually later.
326
+
327
+ ### "GITHUB_TOKEN not set in root .env"
328
+
329
+ **Cause**: Trying to create GitHub remote without `GITHUB_TOKEN` in monorepo `.env`.
330
+
331
+ **Workaround**: Use `--skip-remote` or set `GITHUB_TOKEN` and try again.
332
+
333
+ ### "VERCEL_TOKEN not set — skipping Vercel integration"
334
+
335
+ **Cause**: Trying to link Vercel without `VERCEL_TOKEN` in monorepo `.env` or environment.
336
+
337
+ **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).
338
+
339
+ ### "Region generation failed"
340
+
341
+ **Cause**: `--generate-regions` could not connect to the backend (timeout, wrong URL, wrong API key).
342
+
343
+ **Behavior**: The scaffold does **not** fail. A fallback English-only `regions-config.ts` is generated automatically.
344
+
345
+ **Fix**: Verify credentials in `.env`, then run:
346
+ ```bash
347
+ cd projects/my-store
348
+ yarn generate:regions
349
+ ```
350
+
351
+ ### "`--generate-regions` skipped: requires dependencies"
352
+
353
+ **Cause**: `--generate-regions` was used together with `--skip-install`.
354
+
355
+ **Fix**: Install dependencies first, then run region generation manually:
356
+ ```bash
357
+ yarn install && yarn generate:regions
358
+ ```
359
+
360
+ ### "yarn install failed — run it manually"
361
+
362
+ **Cause**: Missing dependencies or network issues.
363
+
364
+ **Fix**:
365
+ ```bash
366
+ cd projects/my-store
367
+ yarn install
368
+ ```
369
+
370
+ ### "Node.js version too old"
371
+
372
+ **Cause**: Using Node < 18.17.
373
+
374
+ **Fix**:
375
+ ```bash
376
+ nvm install 18.17.0
377
+ nvm use 18.17.0
378
+ ```
379
+
380
+ ---
381
+
382
+ ## Development
383
+
384
+ ### Build from source
385
+
386
+ ```bash
387
+ cd packages/create-thor-app
388
+ yarn build
389
+ ```
390
+
391
+ This runs `tsup` which compiles `src/` and then bundles `packages/core` → `templates/default/` via the `onSuccess` hook.
392
+
393
+ ### Test locally
394
+
395
+ ```bash
396
+ # Monorepo mode
397
+ node packages/create-thor-app/dist/index.js test-app --skip-install --skip-git
398
+
399
+ # Check output
400
+ ls projects/test-app/
401
+ ```
402
+
403
+ ### Type-check
404
+
405
+ ```bash
406
+ yarn workspace @thorprovider/create-thor-app type-check
407
+ ```
408
+
409
+ ### Watch mode
410
+
411
+ ```bash
412
+ yarn workspace @thorprovider/create-thor-app dev
413
+ ```
414
+
415
+ ---
416
+
417
+ ## Architecture
418
+
419
+ The package is structured for maintainability:
420
+
421
+ | File | Purpose |
422
+ |------|---------|
423
+ | `src/index.ts` | CLI entry point (Commander.js) |
424
+ | `src/create-app.ts` | Main orchestration logic |
425
+ | `src/types.ts` | Shared TypeScript interfaces |
426
+ | `src/helpers/logger.ts` | Color logging (zero deps) |
427
+ | `src/helpers/template.ts` | Template resolution + copy filter |
428
+ | `src/helpers/package-json.ts` | Dependency resolution |
429
+ | `src/helpers/git.ts` | Git init + GitHub remote creation |
430
+ | `src/helpers/vercel.ts` | Vercel project creation via REST API |
431
+ | `src/helpers/prompts.ts` | Shared TTY-aware interactive prompts |
432
+ | `src/helpers/install.ts` | Yarn install wrapper |
433
+ | `src/helpers/env.ts` | .env + .npmrc creation (accepts overrides for backend flags) |
434
+ | `src/helpers/site-config.ts` | Patches `config/site.config.ts` with `--preset` / `--site-url` |
435
+ | `src/helpers/v0-context.ts` | .v0-context.md generation |
436
+ | `tsup.config.ts` | Build config + template bundling hook (copies regions script) |
437
+
438
+ ### Dual-mode detection
439
+
440
+ `findMonorepoRoot()` walks up the directory tree looking for `packages/core/package.json`:
441
+ - **Found** → Monorepo mode (copy live, resolve deps at runtime)
442
+ - **Not found** → Standalone mode (use `templates/default/`, use pre-baked versions)
443
+
444
+ ---
445
+
446
+ ## Publishing
447
+
448
+ The package is published to GitHub Packages with `publishConfig.access = "restricted"`:
449
+
450
+ ```bash
451
+ yarn changeset
452
+ yarn version-packages
453
+ yarn ci:publish
454
+ ```
455
+
456
+ Only include `@thorprovider/create-thor-app` in changesets if publishing this package alone.
457
+
458
+ ---
459
+
460
+ ## License
461
+
462
+ MIT — See root LICENSE file.
463
+
464
+ ---
465
+
466
+ ## Support
467
+
468
+ - **Issues**: Report in https://github.com/thorprovider/thor-commerce/issues with label `create-thor-app`
469
+ - **Questions**: Ask in internal Slack or GitHub Discussions
470
+ - **Docs**: Read `/packages/core/docs/` for template architecture