@thorprovider/create-thor-app 4.1.9 → 5.0.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 +57 -470
- package/dist/index.js +1 -2
- package/package.json +1 -1
- package/templates/default/.env.example +1 -1
- package/templates/default/.eslintrc.json +0 -4
- package/templates/default/README.md +2 -2
- package/templates/default/ai-validator.json +2 -2
- package/templates/default/app/cart/page.tsx +114 -0
- package/templates/default/app/checkout/page.tsx +395 -0
- package/templates/default/app/checkout/success/page.tsx +43 -0
- package/templates/default/app/layout.tsx +31 -7
- package/templates/default/app/products/[handle]/add-to-cart-button.tsx +85 -0
- package/templates/default/app/products/[handle]/page.tsx +108 -0
- package/templates/default/docs/README.md +0 -1
- package/templates/default/docs/project-structure.md +16 -6
- package/templates/default/docs/rules.md +1 -2
- package/templates/default/lib/commerce-client.ts +2 -3
- package/templates/default/lib/commerce.ts +1 -2
- package/templates/default/lib/env.ts +2 -2
- package/templates/default/lib/theme.ts +40 -0
- package/templates/default/package.json +7 -3
- package/templates/default/playwright.config.ts +86 -0
- package/templates/default/tests/e2e/auth.spec.ts +80 -0
- package/templates/default/tests/e2e/backend-unavailable.spec.ts +25 -0
- package/templates/default/tests/e2e/cart.spec.ts +79 -0
- package/templates/default/tests/e2e/checkout.spec.ts +95 -0
- package/templates/default/tests/e2e/global-setup.ts +42 -0
- package/templates/default/tests/e2e/product.spec.ts +53 -0
- package/templates/default/tests/e2e/smoke.spec.ts +48 -0
package/README.md
CHANGED
|
@@ -1,506 +1,93 @@
|
|
|
1
1
|
---
|
|
2
|
-
title: create-thor-app
|
|
3
|
-
purpose:
|
|
4
|
-
lastReviewed: "2026-05-
|
|
2
|
+
title: "@thorprovider/create-thor-app"
|
|
3
|
+
purpose: "ABANDONED — Deprecated scaffolding CLI. Do not use for new work."
|
|
4
|
+
lastReviewed: "2026-05-28"
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
> **⚠️ ABANDONED**
|
|
8
|
+
>
|
|
9
|
+
> `@thorprovider/create-thor-app` **ya no se usa**. No lo utilices para generar proyectos nuevos ni consultes sus templates como referencia.
|
|
10
|
+
>
|
|
11
|
+
> - **App de referencia canónica:** `projects/electrostore` (host SSR sobre `@thorprovider/runtime` + `@thorprovider/blocks` + `@thorprovider/adapters`).
|
|
12
|
+
> - Si un agente o persona encuentra este paquete, debe ignorarlo y mirar `projects/electrostore` en su lugar.
|
|
8
13
|
|
|
9
|
-
|
|
14
|
+
# @thorprovider/create-thor-app
|
|
10
15
|
|
|
11
|
-
|
|
16
|
+
CLI for scaffolding a new Thor Commerce application from the current template.
|
|
12
17
|
|
|
13
|
-
|
|
14
|
-
- **Monorepo mode**: Copy live `packages/core`, run from within the monorepo
|
|
15
|
-
- **Standalone mode**: Use bundled template, run via `npx` from anywhere
|
|
18
|
+
## Deprecation notice
|
|
16
19
|
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
+
This package is **abandoned**. The Thor Commerce monorepo is now the owner of its own
|
|
21
|
+
reference apps (`projects/electrostore`), so no scaffolding CLI is needed. The content
|
|
22
|
+
below documents the historical implementation and is kept only for audit purposes.
|
|
20
23
|
|
|
21
|
-
|
|
24
|
+
## Verified facts
|
|
22
25
|
|
|
23
|
-
|
|
26
|
+
- Package name: `@thorprovider/create-thor-app`
|
|
27
|
+
- Current package version: `4.1.9`
|
|
28
|
+
- Minimum supported Node.js version: `18.17.0`
|
|
29
|
+
- CLI entry uses `commander`
|
|
30
|
+
- The CLI supports both monorepo mode and standalone mode
|
|
24
31
|
|
|
25
|
-
|
|
26
|
-
# Run directly without installing (recommended)
|
|
27
|
-
npx @thorprovider/create-thor-app my-store
|
|
32
|
+
## How it decides what to copy
|
|
28
33
|
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
```
|
|
34
|
+
- Inside this monorepo, it copies the live `packages/core` template and defaults output to `projects/<name>`.
|
|
35
|
+
- Outside this monorepo, it uses `templates/default` and defaults output to `./<name>`.
|
|
32
36
|
|
|
33
|
-
|
|
37
|
+
## Default runtime mode
|
|
34
38
|
|
|
35
|
-
|
|
36
|
-
```bash
|
|
37
|
-
yarn create:app --name my-store
|
|
38
|
-
```
|
|
39
|
+
Generated apps are mock-first by default.
|
|
39
40
|
|
|
40
|
-
|
|
41
|
+
If both backend URL and backend API key are provided, the generated `.env` is configured for a live provider instead.
|
|
41
42
|
|
|
42
43
|
## Usage
|
|
43
44
|
|
|
44
|
-
|
|
45
|
+
Standalone:
|
|
45
46
|
|
|
46
|
-
When run from within the Thor Commerce monorepo, the CLI auto-detects and:
|
|
47
|
-
- Copies live `packages/core` template
|
|
48
|
-
- Resolves `workspace:*` deps to live monorepo versions at build time
|
|
49
|
-
- Places the new project in `projects/<name>/`
|
|
50
|
-
|
|
51
|
-
**Setup Git environment** (optional, for remote repo creation):
|
|
52
|
-
```bash
|
|
53
|
-
# In the monorepo root .env
|
|
54
|
-
GITHUB_TOKEN=ghp_xxxxx
|
|
55
|
-
GITHUB_ORG=myorg # (optional — defaults to user)
|
|
56
|
-
GITHUB_REPO_VISIBILITY=public # (default: private)
|
|
57
|
-
GIT_AUTHOR_NAME=Your Name # (default: "Thor Commerce")
|
|
58
|
-
GIT_AUTHOR_EMAIL=you@example.com
|
|
59
|
-
```
|
|
60
|
-
|
|
61
|
-
**Setup Vercel environment** (optional, for Vercel project linking):
|
|
62
|
-
```bash
|
|
63
|
-
# In the monorepo root .env
|
|
64
|
-
VERCEL_TOKEN=your_vercel_token
|
|
65
|
-
VERCEL_TEAM_SLUG=my-team # (optional — defaults to personal account)
|
|
66
|
-
```
|
|
67
|
-
|
|
68
|
-
**Examples**:
|
|
69
|
-
```bash
|
|
70
|
-
# Interactive prompt
|
|
71
|
-
yarn create:app
|
|
72
|
-
|
|
73
|
-
# With name
|
|
74
|
-
yarn create:app --name my-store
|
|
75
|
-
|
|
76
|
-
# Full options
|
|
77
|
-
yarn create:app --name my-store \
|
|
78
|
-
--skip-git \
|
|
79
|
-
--skip-install \
|
|
80
|
-
--skip-remote \
|
|
81
|
-
--skip-vercel \
|
|
82
|
-
--no-context
|
|
83
|
-
|
|
84
|
-
# Full backend setup in one command
|
|
85
|
-
yarn create:app --name my-store \
|
|
86
|
-
--commerce-provider medusa \
|
|
87
|
-
--commerce-api-url https://my-backend.com \
|
|
88
|
-
--commerce-api-key pk_live_xxx
|
|
89
|
-
|
|
90
|
-
# With backend configuration
|
|
91
|
-
yarn create:app --name my-store \
|
|
92
|
-
--commerce-provider medusa \
|
|
93
|
-
--commerce-api-url http://localhost:9000 \
|
|
94
|
-
--commerce-api-key pk_abc123
|
|
95
|
-
|
|
96
|
-
# Custom output directory
|
|
97
|
-
yarn create:app --name my-store --output /path/to/projects/my-store
|
|
98
|
-
```
|
|
99
|
-
|
|
100
|
-
### Standalone Mode (npx)
|
|
101
|
-
|
|
102
|
-
When run outside the monorepo with `npx`, uses the pre-bundled template:
|
|
103
47
|
```bash
|
|
104
48
|
npx @thorprovider/create-thor-app my-store
|
|
105
49
|
```
|
|
106
50
|
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
**Differences from monorepo mode**:
|
|
110
|
-
- Template is frozen at build time (versions pre-baked into `templates/default/package.json`)
|
|
111
|
-
- No live dependency resolution — uses versions from the last build
|
|
112
|
-
|
|
113
|
-
---
|
|
114
|
-
|
|
115
|
-
## CLI Options
|
|
116
|
-
|
|
117
|
-
| Flag | Description | Default |
|
|
118
|
-
|------|-------------|---------|
|
|
119
|
-
| `--name <name>` | Project name (kebab-case) | Prompt if missing |
|
|
120
|
-
| `-o, --output <dir>` | Output directory | `./<name>` |
|
|
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 |
|
|
124
|
-
| `--skip-git` | Skip git initialization | `false` |
|
|
125
|
-
| `--skip-install` | Skip yarn install | `false` |
|
|
126
|
-
| `--skip-remote` | Skip GitHub remote repo creation | `false` |
|
|
127
|
-
| `--skip-vercel` | Skip Vercel project linking | `false` |
|
|
128
|
-
| `--no-context` | Skip .agents/ directory generation | `false` |
|
|
129
|
-
| `-h, --help` | Show help | — |
|
|
130
|
-
|
|
131
|
-
> **Security note**: `--commerce-api-key` values appear in shell history.
|
|
132
|
-
> For sensitive keys, prefer editing `.env` manually after scaffolding.
|
|
133
|
-
|
|
134
|
-
---
|
|
135
|
-
|
|
136
|
-
## Interactive Prompts
|
|
137
|
-
|
|
138
|
-
When run with **no arguments**, prompts for project name:
|
|
139
|
-
```bash
|
|
140
|
-
$ yarn create:app
|
|
141
|
-
? Project name (kebab-case): _
|
|
142
|
-
```
|
|
143
|
-
|
|
144
|
-
After scaffolding files, the CLI interactively asks (with TTY defaults):
|
|
145
|
-
```bash
|
|
146
|
-
? Create a GitHub remote repository? (Y/n): _
|
|
147
|
-
? Link project to Vercel for automatic deployments? (y/N): _
|
|
148
|
-
```
|
|
149
|
-
|
|
150
|
-
- In **non-interactive environments** (CI, piped stdin), these default to their respective flags (`Y` for GitHub remote, `N` for Vercel).
|
|
151
|
-
- Pass `--skip-remote` or `--skip-vercel` to suppress the prompts entirely.
|
|
152
|
-
|
|
153
|
-
---
|
|
154
|
-
|
|
155
|
-
## Output
|
|
156
|
-
|
|
157
|
-
After successful scaffolding, the CLI prints next steps:
|
|
158
|
-
|
|
159
|
-
```
|
|
160
|
-
✅ Project created successfully!
|
|
161
|
-
|
|
162
|
-
Next steps:
|
|
163
|
-
|
|
164
|
-
1. Backend already configured (via CLI flags) ✓ ← (when --commerce-api-url + --commerce-api-key were used)
|
|
165
|
-
|
|
166
|
-
— or —
|
|
167
|
-
|
|
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
|
|
175
|
-
|
|
176
|
-
2. Add GitHub Actions secrets: ← (only when Vercel link succeeded)
|
|
177
|
-
https://github.com/<org>/my-store/settings/secrets/actions
|
|
178
|
-
|
|
179
|
-
— or —
|
|
180
|
-
|
|
181
|
-
2. Link to Vercel (when ready): ← (when Vercel was skipped)
|
|
182
|
-
cd projects/my-store && vercel link
|
|
183
|
-
|
|
184
|
-
3. Connect to V0:
|
|
185
|
-
Open https://v0.dev → New project → Connect GitHub repo
|
|
186
|
-
V0 will auto-discover .agents/AGENTS.md for context
|
|
187
|
-
|
|
188
|
-
4. Start developing:
|
|
189
|
-
cd projects/my-store && yarn dev
|
|
190
|
-
```
|
|
191
|
-
|
|
192
|
-
**Generated structure**:
|
|
193
|
-
```
|
|
194
|
-
projects/my-store/
|
|
195
|
-
├── .env # Commerce config (mock by default, live backend optional)
|
|
196
|
-
├── .agents/
|
|
197
|
-
│ ├── AGENTS.md # Entry point for AI agents (V0, Claude Code, OpenCode)
|
|
198
|
-
│ ├── context/ # Architecture, types, API, patterns, rules
|
|
199
|
-
│ │ ├── architecture.md
|
|
200
|
-
│ │ ├── project-structure.md
|
|
201
|
-
│ │ ├── types.md
|
|
202
|
-
│ │ ├── commerce-api.md
|
|
203
|
-
│ │ ├── patterns.md
|
|
204
|
-
│ │ └── rules.md
|
|
205
|
-
│ └── skills/ # Playbooks for repeatable tasks
|
|
206
|
-
│ ├── generate-page.md
|
|
207
|
-
│ ├── generate-component.md
|
|
208
|
-
│ ├── generate-module.md
|
|
209
|
-
│ ├── add-commerce-feature.md
|
|
210
|
-
│ ├── add-route.md
|
|
211
|
-
│ └── audit-changes.md
|
|
212
|
-
├── .vercel/
|
|
213
|
-
│ └── project.json # Vercel org/project IDs (when Vercel linked)
|
|
214
|
-
├── .github/
|
|
215
|
-
│ └── workflows/
|
|
216
|
-
│ └── vercel-deploy.yml # CI/CD deploy workflow (when Vercel linked)
|
|
217
|
-
├── package.json # @thorprovider/my-store, updated deps
|
|
218
|
-
├── app/ # Next.js 16 app directory
|
|
219
|
-
├── components/ # UI components
|
|
220
|
-
├── lib/ # Commerce config, env, utilities
|
|
221
|
-
├── styles/ # Theme tokens
|
|
222
|
-
└── ...
|
|
223
|
-
```
|
|
224
|
-
|
|
225
|
-
---
|
|
226
|
-
|
|
227
|
-
## What Gets Generated
|
|
228
|
-
|
|
229
|
-
### package.json
|
|
230
|
-
|
|
231
|
-
- **Name**: `@thorprovider/<name>`
|
|
232
|
-
- **Dependencies**: All `workspace:*` refs → `^X.Y.Z` (pre-baked versions)
|
|
233
|
-
- **Scripts configured**:
|
|
234
|
-
- `dev`, `build`, `start`: Next.js commands
|
|
235
|
-
- `type-check`: TypeScript validation
|
|
236
|
-
|
|
237
|
-
### .agents/
|
|
238
|
-
|
|
239
|
-
Contains persistent AI context for V0 and other agents (Claude Code, OpenCode, Cursor, etc.).
|
|
240
|
-
Inspired by Claude Code's `CLAUDE.md + .claude/skills/` and OpenCode's `AGENTS.md + .opencode/agents/` patterns.
|
|
241
|
-
|
|
242
|
-
Structure:
|
|
243
|
-
- **`AGENTS.md`** — root entry point: what the app is, what agents can/cannot do, read order
|
|
244
|
-
- **`context/`** — architecture rules, types, API signatures, patterns, hard constraints (adapted from `packages/core/docs/`)
|
|
245
|
-
- **`skills/`** — playbooks for repeatable tasks (generate-page, generate-component, audit-changes, etc.)
|
|
246
|
-
|
|
247
|
-
Use `--no-context` to skip generation.
|
|
248
|
-
|
|
249
|
-
### .env
|
|
250
|
-
|
|
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
|
|
255
|
-
|
|
256
|
-
### .vercel/project.json (conditional)
|
|
257
|
-
|
|
258
|
-
Created when Vercel linking succeeds. Contains `orgId` and `projectId` required by `vercel` CLI and the GitHub Actions workflow. Generated automatically — do not edit manually.
|
|
259
|
-
|
|
260
|
-
### .github/workflows/vercel-deploy.yml (conditional)
|
|
261
|
-
|
|
262
|
-
Generated when Vercel linking succeeds. Deploys to Vercel on every push to `main` and posts preview URLs on pull requests.
|
|
263
|
-
|
|
264
|
-
Required GitHub Actions secrets (printed during scaffolding):
|
|
265
|
-
- `VERCEL_TOKEN` — Vercel Access Token
|
|
266
|
-
- `VERCEL_ORG_ID` — From `.vercel/project.json`
|
|
267
|
-
- `VERCEL_PROJECT_ID` — From `.vercel/project.json`
|
|
268
|
-
|
|
269
|
-
---
|
|
270
|
-
|
|
271
|
-
## Examples
|
|
272
|
-
|
|
273
|
-
### Create a new storefront in monorepo
|
|
51
|
+
From this monorepo root:
|
|
274
52
|
|
|
275
53
|
```bash
|
|
276
|
-
|
|
277
|
-
yarn create:app --name my-shop
|
|
278
|
-
cd projects/my-shop
|
|
279
|
-
yarn dev
|
|
280
|
-
```
|
|
281
|
-
|
|
282
|
-
### Scaffold + push to GitHub
|
|
283
|
-
|
|
284
|
-
```bash
|
|
285
|
-
# In monorepo root, set .env
|
|
286
|
-
export GITHUB_TOKEN=ghp_xxxxx
|
|
287
|
-
export GITHUB_ORG=my-org
|
|
288
|
-
|
|
289
|
-
yarn create:app --name my-shop
|
|
290
|
-
|
|
291
|
-
# Verify the remote was created
|
|
292
|
-
cd projects/my-shop
|
|
293
|
-
git remote -v
|
|
294
|
-
```
|
|
295
|
-
|
|
296
|
-
### Create without git or install (for CI/CD)
|
|
297
|
-
|
|
298
|
-
```bash
|
|
299
|
-
yarn create:app --name my-shop \
|
|
300
|
-
--skip-git \
|
|
301
|
-
--skip-install
|
|
302
|
-
|
|
303
|
-
cd projects/my-shop
|
|
304
|
-
# ... run custom setup (docker build, etc.)
|
|
305
|
-
yarn install
|
|
306
|
-
```
|
|
307
|
-
|
|
308
|
-
### Standalone usage (from outside monorepo)
|
|
309
|
-
|
|
310
|
-
```bash
|
|
311
|
-
npx @thorprovider/create-thor-app my-store
|
|
312
|
-
|
|
313
|
-
cd my-store
|
|
314
|
-
# Optional: update .env with live backend settings, or keep mock mode
|
|
315
|
-
yarn dev
|
|
316
|
-
```
|
|
317
|
-
|
|
318
|
-
---
|
|
319
|
-
|
|
320
|
-
## Troubleshooting
|
|
321
|
-
|
|
322
|
-
### "Cannot find Thor Commerce monorepo"
|
|
323
|
-
|
|
324
|
-
**Cause**: Running from outside the monorepo without `npx` or without the bundled CLI.
|
|
325
|
-
|
|
326
|
-
**Fix**: Use `npx @thorprovider/create-thor-app` or run from within `thor-commerce/`.
|
|
327
|
-
|
|
328
|
-
### "Directory already exists"
|
|
329
|
-
|
|
330
|
-
**Cause**: Output path already exists.
|
|
331
|
-
|
|
332
|
-
**Fix**: Choose a different `--name` or delete the existing directory.
|
|
333
|
-
|
|
334
|
-
### "git init failed"
|
|
335
|
-
|
|
336
|
-
**Cause**: Git not installed or not in `$PATH`.
|
|
337
|
-
|
|
338
|
-
**Workaround**: Use `--skip-git` and initialize manually later.
|
|
339
|
-
|
|
340
|
-
### "GITHUB_TOKEN not set in root .env"
|
|
341
|
-
|
|
342
|
-
**Cause**: Trying to create GitHub remote without `GITHUB_TOKEN` in monorepo `.env`.
|
|
343
|
-
|
|
344
|
-
**Workaround**: Use `--skip-remote` or set `GITHUB_TOKEN` and try again.
|
|
345
|
-
|
|
346
|
-
### "VERCEL_TOKEN not set — skipping Vercel integration"
|
|
347
|
-
|
|
348
|
-
**Cause**: Trying to link Vercel without `VERCEL_TOKEN` in monorepo `.env` or environment.
|
|
349
|
-
|
|
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).
|
|
351
|
-
|
|
352
|
-
### "yarn install failed — run it manually"
|
|
353
|
-
|
|
354
|
-
**Cause**: Missing dependencies or network issues.
|
|
355
|
-
|
|
356
|
-
**Fix**:
|
|
357
|
-
```bash
|
|
358
|
-
cd projects/my-store
|
|
359
|
-
yarn install
|
|
360
|
-
```
|
|
361
|
-
|
|
362
|
-
### "Node.js version too old"
|
|
363
|
-
|
|
364
|
-
**Cause**: Using Node < 18.17.
|
|
365
|
-
|
|
366
|
-
**Fix**:
|
|
367
|
-
```bash
|
|
368
|
-
nvm install 18.17.0
|
|
369
|
-
nvm use 18.17.0
|
|
370
|
-
```
|
|
371
|
-
|
|
372
|
-
---
|
|
373
|
-
|
|
374
|
-
## Development
|
|
375
|
-
|
|
376
|
-
### Build from source
|
|
377
|
-
|
|
378
|
-
```bash
|
|
379
|
-
cd packages/create-thor-app
|
|
380
|
-
yarn build
|
|
54
|
+
yarn create:app --name my-store
|
|
381
55
|
```
|
|
382
56
|
|
|
383
|
-
|
|
57
|
+
## Current CLI options
|
|
384
58
|
|
|
385
|
-
|
|
59
|
+
- positional project name: `[name]`
|
|
60
|
+
- `--name <name>`
|
|
61
|
+
- `-o, --output <dir>`
|
|
62
|
+
- `--skip-git`
|
|
63
|
+
- `--skip-install`
|
|
64
|
+
- `--skip-remote`
|
|
65
|
+
- `--skip-vercel`
|
|
66
|
+
- `--no-context`
|
|
67
|
+
- `--no-validator`
|
|
68
|
+
- `--commerce-provider <provider>`
|
|
69
|
+
- `--commerce-api-url <url>`
|
|
70
|
+
- `--commerce-api-key <key>`
|
|
386
71
|
|
|
387
|
-
|
|
388
|
-
# Monorepo mode
|
|
389
|
-
node packages/create-thor-app/dist/index.js test-app --skip-install --skip-git
|
|
72
|
+
## What the CLI currently generates
|
|
390
73
|
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
74
|
+
- Application files copied from the active template
|
|
75
|
+
- `.env`
|
|
76
|
+
- Optional `.agents/` context files
|
|
77
|
+
- Optional git initialization
|
|
78
|
+
- Optional GitHub remote creation
|
|
79
|
+
- Optional Vercel linking
|
|
394
80
|
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
```bash
|
|
398
|
-
yarn workspace @thorprovider/create-thor-app type-check
|
|
399
|
-
```
|
|
400
|
-
|
|
401
|
-
### Watch mode
|
|
81
|
+
## Workspace commands
|
|
402
82
|
|
|
403
83
|
```bash
|
|
84
|
+
yarn workspace @thorprovider/create-thor-app build
|
|
404
85
|
yarn workspace @thorprovider/create-thor-app dev
|
|
86
|
+
yarn workspace @thorprovider/create-thor-app type-check
|
|
405
87
|
```
|
|
406
88
|
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
## Architecture
|
|
410
|
-
|
|
411
|
-
The package is structured for maintainability:
|
|
412
|
-
|
|
413
|
-
| File | Purpose |
|
|
414
|
-
|------|---------|
|
|
415
|
-
| `src/index.ts` | CLI entry point (Commander.js) |
|
|
416
|
-
| `src/create-app.ts` | Main orchestration logic |
|
|
417
|
-
| `src/types.ts` | Shared TypeScript interfaces |
|
|
418
|
-
| `src/helpers/logger.ts` | Color logging (zero deps) |
|
|
419
|
-
| `src/helpers/template.ts` | Template resolution + copy filter |
|
|
420
|
-
| `src/helpers/package-json.ts` | Dependency resolution |
|
|
421
|
-
| `src/helpers/git.ts` | Git init + GitHub remote creation |
|
|
422
|
-
| `src/helpers/vercel.ts` | Vercel project creation via REST API |
|
|
423
|
-
| `src/helpers/prompts.ts` | Shared TTY-aware interactive prompts |
|
|
424
|
-
| `src/helpers/install.ts` | Yarn install wrapper |
|
|
425
|
-
| `src/helpers/env.ts` | .env creation (accepts backend overrides) |
|
|
426
|
-
| `src/helpers/agents-dir.ts` | .agents/ directory generation (AGENTS.md + context/ + skills/) |
|
|
427
|
-
| `tsup.config.ts` | Build config + template bundling hook |
|
|
428
|
-
|
|
429
|
-
## How V0 is Programmed for ThorBuilder
|
|
430
|
-
|
|
431
|
-
ThorBuilder does not rely on a single prompt. V0 is guided through multiple aligned mechanisms that must stay in sync as the codebase evolves.
|
|
432
|
-
|
|
433
|
-
### Guardrail Layers
|
|
434
|
-
|
|
435
|
-
1. **Template `.agents/AGENTS.md`**
|
|
436
|
-
- Compact mission, architecture, runtime, and conflict-resolution rules
|
|
437
|
-
- Used as project-level instructions and persisted for later chat injection
|
|
438
|
-
|
|
439
|
-
2. **Template docs** (`templates/default/docs/`)
|
|
440
|
-
- `types.md` → domain contracts
|
|
441
|
-
- `commerce-api.md` → all allowed `commerce.*` methods
|
|
442
|
-
- `patterns.md` → canonical implementation patterns
|
|
443
|
-
- `rules.md` → non-negotiable constraints
|
|
444
|
-
- `project-structure.md` → file ownership and boundaries
|
|
445
|
-
- `decision-matrix.md` → fast architecture decisions when prompts create pressure to drift
|
|
446
|
-
|
|
447
|
-
3. **Validator rules** (`templates/default/ai-validator.json`)
|
|
448
|
-
- Regex-based post-generation checks that catch architectural drift
|
|
449
|
-
- Examples: backend SDK imports, raw backend fetches, env gating, alternate backend stacks
|
|
450
|
-
|
|
451
|
-
4. **Dynamic ThorBuilder prompt injection**
|
|
452
|
-
- `thor-commerce-builder/lib/thor-context.ts` injects project config, guardrail policy, and backend guidance at chat time
|
|
453
|
-
- Mode-aware: mock, incomplete real backend config, or live backend configured
|
|
454
|
-
|
|
455
|
-
### Core Programming Rules for V0
|
|
456
|
-
|
|
457
|
-
- Build a **ThorCommerce storefront**, not a generic web app
|
|
458
|
-
- Use **`commerce.*` only** for backend access in starter/app code
|
|
459
|
-
- Never integrate vendors directly via SDKs or raw fetch in L5
|
|
460
|
-
- Respect mock-first / live-immediate runtime behavior
|
|
461
|
-
- Live backend data is authoritative when configured and available
|
|
462
|
-
- Demo fixtures are allowed only for presentation-oriented sections in mock/incomplete mode
|
|
463
|
-
|
|
464
|
-
### Maintenance Rule
|
|
465
|
-
|
|
466
|
-
If you change ThorCommerce architecture, adapters, starter boundaries, or runtime behavior, review **all guardrail layers** together. Do not update AGENTS or validator rules in isolation.
|
|
467
|
-
|
|
468
|
-
See also:
|
|
469
|
-
- `V0_GUARDRAILS_MAINTENANCE.md`
|
|
470
|
-
- `templates/default/docs/decision-matrix.md`
|
|
471
|
-
|
|
472
|
-
### Dual-mode detection
|
|
473
|
-
|
|
474
|
-
`findMonorepoRoot()` walks up the directory tree looking for `packages/core/package.json`:
|
|
475
|
-
- **Found** → Monorepo mode (copy live, resolve deps at runtime)
|
|
476
|
-
- **Not found** → Standalone mode (use `templates/default/`, use pre-baked versions)
|
|
477
|
-
|
|
478
|
-
---
|
|
479
|
-
|
|
480
|
-
## Publishing
|
|
481
|
-
|
|
482
|
-
This package is published publicly to npm through the monorepo Changesets workflow:
|
|
483
|
-
|
|
484
|
-
```bash
|
|
485
|
-
yarn changeset
|
|
486
|
-
# open and merge your PR to main
|
|
487
|
-
# CI versions and publishes on push to main
|
|
488
|
-
```
|
|
489
|
-
|
|
490
|
-
Include `@thorprovider/create-thor-app` in a changeset whenever you change the CLI, its bundled template, or any publishable behavior consumers depend on.
|
|
491
|
-
|
|
492
|
-
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.
|
|
493
|
-
|
|
494
|
-
---
|
|
495
|
-
|
|
496
|
-
## License
|
|
497
|
-
|
|
498
|
-
MIT — See root LICENSE file.
|
|
499
|
-
|
|
500
|
-
---
|
|
501
|
-
|
|
502
|
-
## Support
|
|
89
|
+
## Related docs
|
|
503
90
|
|
|
504
|
-
-
|
|
505
|
-
-
|
|
506
|
-
-
|
|
91
|
+
- [AI_GUARDRAILS_AGENTS.md](./AI_GUARDRAILS_AGENTS.md)
|
|
92
|
+
- [V0_GUARDRAILS_MAINTENANCE.md](./V0_GUARDRAILS_MAINTENANCE.md)
|
|
93
|
+
- [V0_STOP_HOOKS_INTEGRATION.md](./V0_STOP_HOOKS_INTEGRATION.md)
|
package/dist/index.js
CHANGED
|
@@ -440,7 +440,7 @@ L5: this app \u2192 Next.js app + local providers
|
|
|
440
440
|
- Import commerce access from \`@/lib/commerce\`
|
|
441
441
|
- Use \`next/link\` and \`next/image\` directly
|
|
442
442
|
- Local providers live in \`components/providers/\`
|
|
443
|
-
- Do not import \`@thorprovider/components\`
|
|
443
|
+
- Do not import \`@thorprovider/components\`
|
|
444
444
|
- Do not import backend SDKs directly
|
|
445
445
|
|
|
446
446
|
## Frozen Files
|
|
@@ -590,7 +590,6 @@ description: Validate generated code against the current storefront rules.
|
|
|
590
590
|
|
|
591
591
|
- [ ] Types imported from \`@thorprovider/types\`
|
|
592
592
|
- [ ] No \`@thorprovider/components\` imports
|
|
593
|
-
- [ ] No \`@thorprovider/providers\` imports
|
|
594
593
|
- [ ] No backend SDK imports
|
|
595
594
|
- [ ] No raw \`fetch(COMMERCE_API_URL...)\`
|
|
596
595
|
- [ ] Prices rendered with \`formatPrice()\`
|
package/package.json
CHANGED
|
@@ -7,7 +7,7 @@
|
|
|
7
7
|
# ---------------------------------------------------------------------------
|
|
8
8
|
# Commerce Backend (optional)
|
|
9
9
|
# ---------------------------------------------------------------------------
|
|
10
|
-
# Which commerce platform to use: mock | medusa |
|
|
10
|
+
# Which commerce platform to use: mock | medusa | shopify | bigcommerce | custom
|
|
11
11
|
# Use `mock` to design/layout the storefront before a real backend is connected.
|
|
12
12
|
NEXT_PUBLIC_COMMERCE_PROVIDER=mock
|
|
13
13
|
|
|
@@ -19,10 +19,6 @@
|
|
|
19
19
|
"group": ["@thorprovider/components", "@thorprovider/components/*"],
|
|
20
20
|
"message": "This template does NOT use @thorprovider/components. Use shadcn/ui components from @/components/ui/ instead."
|
|
21
21
|
},
|
|
22
|
-
{
|
|
23
|
-
"group": ["@thorprovider/providers", "@thorprovider/providers/*"],
|
|
24
|
-
"message": "This template does NOT use @thorprovider/providers. Providers are local code in @/components/providers/ and @/lib/."
|
|
25
|
-
},
|
|
26
22
|
{
|
|
27
23
|
"group": ["@medusajs/*", "@shopify/*", "@bigcommerce/*"],
|
|
28
24
|
"message": "Never import backend SDKs directly. Use the commerce singleton from @/lib/commerce instead."
|
|
@@ -19,7 +19,6 @@ V0-native storefront template for Thor Commerce Builder. Lean scaffold designed
|
|
|
19
19
|
|
|
20
20
|
**NOT used** (by design):
|
|
21
21
|
- `@thorprovider/components` — V0 creates UI from shadcn/ui (unique UI per client)
|
|
22
|
-
- `@thorprovider/providers` — providers are local code (V0 can read source)
|
|
23
22
|
|
|
24
23
|
## Quick Start
|
|
25
24
|
|
|
@@ -61,7 +60,8 @@ NEXT_PUBLIC_COMMERCE_API_KEY=pk_live_xxx
|
|
|
61
60
|
|------|---------|
|
|
62
61
|
| `lib/commerce.ts` | Commerce singleton (createProvider + lazy proxy) |
|
|
63
62
|
| `lib/env.ts` | Zod-validated environment schema |
|
|
64
|
-
| `lib/
|
|
63
|
+
| `lib/theme.ts` | Accent color → OKLCH mapping |
|
|
64
|
+
| `lib/commerce-client.ts` | Client-safe commerce factory |
|
|
65
65
|
| `components/providers/app-providers.tsx` | Provider chain (order is critical) |
|
|
66
66
|
|
|
67
67
|
## What's Pre-Configured
|
|
@@ -144,8 +144,8 @@
|
|
|
144
144
|
{
|
|
145
145
|
"id": "no-thorprovider-components-import",
|
|
146
146
|
"filePattern": "**/*.{ts,tsx}",
|
|
147
|
-
"pattern": "from\\s+['\"]@thorprovider/components['\"]
|
|
148
|
-
"description": "Do not import from @thorprovider/components
|
|
147
|
+
"pattern": "from\\s+['\"]@thorprovider/components['\"]",
|
|
148
|
+
"description": "Do not import from @thorprovider/components — use shadcn/ui for UI"
|
|
149
149
|
},
|
|
150
150
|
{
|
|
151
151
|
"id": "no-alternate-backend-stacks-in-app",
|