@thorprovider/create-thor-app 4.1.9 → 4.2.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 +47 -473
- package/package.json +1 -1
- package/templates/default/.env.example +1 -1
- package/templates/default/README.md +2 -1
- 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/project-structure.md +16 -6
- package/templates/default/lib/commerce-client.ts +1 -1
- 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,80 @@
|
|
|
1
1
|
---
|
|
2
|
-
title: create-thor-app
|
|
3
|
-
purpose:
|
|
4
|
-
lastReviewed: "2026-05-
|
|
2
|
+
title: "@thorprovider/create-thor-app"
|
|
3
|
+
purpose: "Verified entry point for the Thor Commerce scaffolding CLI"
|
|
4
|
+
lastReviewed: "2026-05-28"
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
-
# create-thor-app
|
|
7
|
+
# @thorprovider/create-thor-app
|
|
8
8
|
|
|
9
|
-
CLI scaffolding
|
|
9
|
+
CLI for scaffolding a new Thor Commerce application from the current template.
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
## Verified facts
|
|
12
12
|
|
|
13
|
-
|
|
14
|
-
-
|
|
15
|
-
-
|
|
13
|
+
- Package name: `@thorprovider/create-thor-app`
|
|
14
|
+
- Current package version: `4.1.9`
|
|
15
|
+
- Minimum supported Node.js version: `18.17.0`
|
|
16
|
+
- CLI entry uses `commander`
|
|
17
|
+
- The CLI supports both monorepo mode and standalone mode
|
|
16
18
|
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
## Installation
|
|
20
|
-
|
|
21
|
-
### npm (Public Package)
|
|
22
|
-
|
|
23
|
-
This package is published publicly to npm:
|
|
24
|
-
|
|
25
|
-
```bash
|
|
26
|
-
# Run directly without installing (recommended)
|
|
27
|
-
npx @thorprovider/create-thor-app my-store
|
|
19
|
+
## How it decides what to copy
|
|
28
20
|
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
```
|
|
21
|
+
- Inside this monorepo, it copies the live `packages/core` template and defaults output to `projects/<name>`.
|
|
22
|
+
- Outside this monorepo, it uses `templates/default` and defaults output to `./<name>`.
|
|
32
23
|
|
|
33
|
-
|
|
24
|
+
## Default runtime mode
|
|
34
25
|
|
|
35
|
-
|
|
36
|
-
```bash
|
|
37
|
-
yarn create:app --name my-store
|
|
38
|
-
```
|
|
26
|
+
Generated apps are mock-first by default.
|
|
39
27
|
|
|
40
|
-
|
|
28
|
+
If both backend URL and backend API key are provided, the generated `.env` is configured for a live provider instead.
|
|
41
29
|
|
|
42
30
|
## Usage
|
|
43
31
|
|
|
44
|
-
|
|
45
|
-
|
|
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
|
-
```bash
|
|
104
|
-
npx @thorprovider/create-thor-app my-store
|
|
105
|
-
```
|
|
106
|
-
|
|
107
|
-
If you do not pass backend flags, the generated app starts in mock mode by default.
|
|
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
|
|
274
|
-
|
|
275
|
-
```bash
|
|
276
|
-
cd thor-commerce
|
|
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)
|
|
32
|
+
Standalone:
|
|
309
33
|
|
|
310
34
|
```bash
|
|
311
35
|
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
36
|
```
|
|
361
37
|
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
**Cause**: Using Node < 18.17.
|
|
38
|
+
From this monorepo root:
|
|
365
39
|
|
|
366
|
-
**Fix**:
|
|
367
40
|
```bash
|
|
368
|
-
|
|
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
|
|
41
|
+
yarn create:app --name my-store
|
|
381
42
|
```
|
|
382
43
|
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
### Test locally
|
|
386
|
-
|
|
387
|
-
```bash
|
|
388
|
-
# Monorepo mode
|
|
389
|
-
node packages/create-thor-app/dist/index.js test-app --skip-install --skip-git
|
|
44
|
+
## Current CLI options
|
|
390
45
|
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
46
|
+
- positional project name: `[name]`
|
|
47
|
+
- `--name <name>`
|
|
48
|
+
- `-o, --output <dir>`
|
|
49
|
+
- `--skip-git`
|
|
50
|
+
- `--skip-install`
|
|
51
|
+
- `--skip-remote`
|
|
52
|
+
- `--skip-vercel`
|
|
53
|
+
- `--no-context`
|
|
54
|
+
- `--no-validator`
|
|
55
|
+
- `--commerce-provider <provider>`
|
|
56
|
+
- `--commerce-api-url <url>`
|
|
57
|
+
- `--commerce-api-key <key>`
|
|
394
58
|
|
|
395
|
-
|
|
59
|
+
## What the CLI currently generates
|
|
396
60
|
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
61
|
+
- Application files copied from the active template
|
|
62
|
+
- `.env`
|
|
63
|
+
- Optional `.agents/` context files
|
|
64
|
+
- Optional git initialization
|
|
65
|
+
- Optional GitHub remote creation
|
|
66
|
+
- Optional Vercel linking
|
|
400
67
|
|
|
401
|
-
|
|
68
|
+
## Workspace commands
|
|
402
69
|
|
|
403
70
|
```bash
|
|
71
|
+
yarn workspace @thorprovider/create-thor-app build
|
|
404
72
|
yarn workspace @thorprovider/create-thor-app dev
|
|
73
|
+
yarn workspace @thorprovider/create-thor-app type-check
|
|
405
74
|
```
|
|
406
75
|
|
|
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
|
|
76
|
+
## Related docs
|
|
503
77
|
|
|
504
|
-
-
|
|
505
|
-
-
|
|
506
|
-
-
|
|
78
|
+
- [AI_GUARDRAILS_AGENTS.md](./AI_GUARDRAILS_AGENTS.md)
|
|
79
|
+
- [V0_GUARDRAILS_MAINTENANCE.md](./V0_GUARDRAILS_MAINTENANCE.md)
|
|
80
|
+
- [V0_STOP_HOOKS_INTEGRATION.md](./V0_STOP_HOOKS_INTEGRATION.md)
|
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
|
|
|
@@ -61,7 +61,8 @@ NEXT_PUBLIC_COMMERCE_API_KEY=pk_live_xxx
|
|
|
61
61
|
|------|---------|
|
|
62
62
|
| `lib/commerce.ts` | Commerce singleton (createProvider + lazy proxy) |
|
|
63
63
|
| `lib/env.ts` | Zod-validated environment schema |
|
|
64
|
-
| `lib/
|
|
64
|
+
| `lib/theme.ts` | Accent color → OKLCH mapping |
|
|
65
|
+
| `lib/commerce-client.ts` | Client-safe commerce factory |
|
|
65
66
|
| `components/providers/app-providers.tsx` | Provider chain (order is critical) |
|
|
66
67
|
|
|
67
68
|
## What's Pre-Configured
|
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
'use client'
|
|
2
|
+
|
|
3
|
+
import React from 'react'
|
|
4
|
+
import Link from 'next/link'
|
|
5
|
+
import { useCart } from '@/components/providers/cart-provider'
|
|
6
|
+
import { formatPrice } from '@/lib/utils'
|
|
7
|
+
|
|
8
|
+
export default function CartPage() {
|
|
9
|
+
const { cart, items, isLoading, removeItem, updateQuantity } = useCart()
|
|
10
|
+
|
|
11
|
+
if (items.length === 0) {
|
|
12
|
+
return (
|
|
13
|
+
<main className="container mx-auto px-4 py-16 text-center">
|
|
14
|
+
<h1 className="text-2xl font-bold">Your cart is empty</h1>
|
|
15
|
+
<p className="mt-2 text-muted-foreground">Add some products to get started.</p>
|
|
16
|
+
<Link
|
|
17
|
+
className="mt-6 inline-block rounded-lg bg-primary px-6 py-3 text-sm font-semibold text-primary-foreground"
|
|
18
|
+
href="/"
|
|
19
|
+
>
|
|
20
|
+
Continue shopping
|
|
21
|
+
</Link>
|
|
22
|
+
</main>
|
|
23
|
+
)
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
return (
|
|
27
|
+
<main className="container mx-auto px-4 py-8">
|
|
28
|
+
<h1 className="mb-6 text-2xl font-bold">Cart</h1>
|
|
29
|
+
|
|
30
|
+
<div className="grid gap-8 lg:grid-cols-3">
|
|
31
|
+
{/* Line items */}
|
|
32
|
+
<div className="lg:col-span-2 flex flex-col gap-4">
|
|
33
|
+
{items.map((item) => {
|
|
34
|
+
const product = item.merchandise.product
|
|
35
|
+
return (
|
|
36
|
+
<div
|
|
37
|
+
className="flex gap-4 rounded-xl border bg-card p-4"
|
|
38
|
+
key={item.id ?? item.merchandise.id}
|
|
39
|
+
>
|
|
40
|
+
{product.featuredImage && (
|
|
41
|
+
<div className="h-20 w-20 flex-shrink-0 overflow-hidden rounded-lg bg-muted">
|
|
42
|
+
<img
|
|
43
|
+
alt={product.featuredImage.altText || product.title}
|
|
44
|
+
className="h-full w-full object-cover"
|
|
45
|
+
src={product.featuredImage.url}
|
|
46
|
+
/>
|
|
47
|
+
</div>
|
|
48
|
+
)}
|
|
49
|
+
<div className="flex flex-1 flex-col gap-1">
|
|
50
|
+
<p className="font-semibold">{product.title}</p>
|
|
51
|
+
{item.merchandise.title && item.merchandise.title !== 'Default Title' && (
|
|
52
|
+
<p className="text-sm text-muted-foreground">{item.merchandise.title}</p>
|
|
53
|
+
)}
|
|
54
|
+
<p className="text-sm font-medium">{formatPrice(item.cost.totalAmount)}</p>
|
|
55
|
+
</div>
|
|
56
|
+
<div className="flex flex-col items-end gap-2">
|
|
57
|
+
<button
|
|
58
|
+
aria-label="Remove item"
|
|
59
|
+
className="text-muted-foreground hover:text-destructive transition-colors"
|
|
60
|
+
disabled={isLoading}
|
|
61
|
+
onClick={() => item.id && removeItem(item.id)}
|
|
62
|
+
type="button"
|
|
63
|
+
>
|
|
64
|
+
×
|
|
65
|
+
</button>
|
|
66
|
+
<input
|
|
67
|
+
className="w-14 rounded-md border bg-background px-2 py-1 text-center text-sm"
|
|
68
|
+
disabled={isLoading}
|
|
69
|
+
min={1}
|
|
70
|
+
onChange={(e) => {
|
|
71
|
+
const qty = Math.max(1, parseInt(e.target.value, 10) || 1)
|
|
72
|
+
if (item.id) updateQuantity(item.id, qty)
|
|
73
|
+
}}
|
|
74
|
+
type="number"
|
|
75
|
+
value={item.quantity}
|
|
76
|
+
/>
|
|
77
|
+
</div>
|
|
78
|
+
</div>
|
|
79
|
+
)
|
|
80
|
+
})}
|
|
81
|
+
</div>
|
|
82
|
+
|
|
83
|
+
{/* Summary */}
|
|
84
|
+
<div className="rounded-xl border bg-card p-6 h-fit flex flex-col gap-4">
|
|
85
|
+
<h2 className="font-semibold text-lg">Order summary</h2>
|
|
86
|
+
{cart && (
|
|
87
|
+
<>
|
|
88
|
+
<div className="flex justify-between text-sm">
|
|
89
|
+
<span className="text-muted-foreground">Subtotal</span>
|
|
90
|
+
<span>{formatPrice(cart.cost.subtotalAmount)}</span>
|
|
91
|
+
</div>
|
|
92
|
+
<div className="border-t pt-3 flex justify-between font-semibold">
|
|
93
|
+
<span>Total</span>
|
|
94
|
+
<span>{formatPrice(cart.cost.totalAmount)}</span>
|
|
95
|
+
</div>
|
|
96
|
+
</>
|
|
97
|
+
)}
|
|
98
|
+
<Link
|
|
99
|
+
className="rounded-lg bg-primary px-6 py-3 text-center text-sm font-semibold text-primary-foreground"
|
|
100
|
+
href="/checkout"
|
|
101
|
+
>
|
|
102
|
+
Proceed to checkout
|
|
103
|
+
</Link>
|
|
104
|
+
<Link
|
|
105
|
+
className="text-center text-sm text-muted-foreground underline-offset-4 hover:underline"
|
|
106
|
+
href="/"
|
|
107
|
+
>
|
|
108
|
+
Continue shopping
|
|
109
|
+
</Link>
|
|
110
|
+
</div>
|
|
111
|
+
</div>
|
|
112
|
+
</main>
|
|
113
|
+
)
|
|
114
|
+
}
|