title: create-thor-app purpose: CLI scaffolding tool for generating new Thor Commerce applications from the core template lastReviewed: "2026-05-01"

create-thor-app

CLI scaffolding tool to generate a new Thor Commerce application from the @thorprovider/core template.

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.

Supports dual-mode operation:

• Monorepo mode: Copy live packages/core, run from within the monorepo
• Standalone mode: Use bundled template, run via npx from anywhere

Installation

npm (Public Package)

This package is published publicly to npm:

# Run directly without installing (recommended)
npx @thorprovider/create-thor-app my-store

# Or install globally
npm install -g @thorprovider/create-thor-app

From Monorepo

Run directly from the monorepo (no publish required):

yarn create:app --name my-store

Usage

Monorepo Mode

When run from within the Thor Commerce monorepo, the CLI auto-detects and:

• Copies live packages/core template
• Resolves workspace:* deps to live monorepo versions at build time
• Places the new project in projects/<name>/

Setup Git environment (optional, for remote repo creation):

# In the monorepo root .env
GITHUB_TOKEN=ghp_xxxxx
GITHUB_ORG=myorg              # (optional — defaults to user)
GITHUB_REPO_VISIBILITY=public # (default: private)
GIT_AUTHOR_NAME=Your Name     # (default: "Thor Commerce")
[email protected]

Setup Vercel environment (optional, for Vercel project linking):

# In the monorepo root .env
VERCEL_TOKEN=your_vercel_token
VERCEL_TEAM_SLUG=my-team      # (optional — defaults to personal account)

Examples:

# Interactive prompt
yarn create:app

# With name
yarn create:app --name my-store

# Full options
yarn create:app --name my-store \
  --skip-git \
  --skip-install \
  --skip-remote \
  --skip-vercel \
  --no-context

# Full backend setup in one command
yarn create:app --name my-store \
  --commerce-provider medusa \
  --commerce-api-url https://my-backend.com \
  --commerce-api-key pk_live_xxx

# With backend configuration
yarn create:app --name my-store \
  --commerce-provider medusa \
  --commerce-api-url http://localhost:9000 \
  --commerce-api-key pk_abc123

# Custom output directory
yarn create:app --name my-store --output /path/to/projects/my-store

Standalone Mode (npx)

When run outside the monorepo with npx, uses the pre-bundled template:

npx @thorprovider/create-thor-app my-store

If you do not pass backend flags, the generated app starts in mock mode by default.

Differences from monorepo mode:

• Template is frozen at build time (versions pre-baked into templates/default/package.json)
• No live dependency resolution — uses versions from the last build

CLI Options

| Flag | Description | Default | |------|-------------|---------| | --name <name> | Project name (kebab-case) | Prompt if missing | | -o, --output <dir> | Output directory | ./<name> | | --commerce-provider <p> | Commerce backend (mock, medusa, shopify) → .env | mock | | --commerce-api-url <url> | Backend API URL → .env (required only for real backends) | http://localhost:9000 | | --commerce-api-key <key> | Publishable API key → .env (required only for real backends) | placeholder | | --skip-git | Skip git initialization | false | | --skip-install | Skip yarn install | false | | --skip-remote | Skip GitHub remote repo creation | false | | --skip-vercel | Skip Vercel project linking | false | | --no-context | Skip .agents/ directory generation | false | | -h, --help | Show help | — |

Security note: --commerce-api-key values appear in shell history. For sensitive keys, prefer editing .env manually after scaffolding.

Interactive Prompts

When run with no arguments, prompts for project name:

$ yarn create:app
? Project name (kebab-case): _

After scaffolding files, the CLI interactively asks (with TTY defaults):

? Create a GitHub remote repository? (Y/n): _
? Link project to Vercel for automatic deployments? (y/N): _

• In non-interactive environments (CI, piped stdin), these default to their respective flags (Y for GitHub remote, N for Vercel).
• Pass --skip-remote or --skip-vercel to suppress the prompts entirely.

Output

After successful scaffolding, the CLI prints next steps:

✅ Project created successfully!

Next steps:

1. Backend already configured (via CLI flags) ✓   ← (when --commerce-api-url + --commerce-api-key were used)

   — or —

1. Start in mock mode immediately:
   `projects/my-store/.env` already defaults to `NEXT_PUBLIC_COMMERCE_PROVIDER=mock`

   — or —

1. Configure your live backend:
   Edit `projects/my-store/.env` with your commerce backend URL and API key

2. Add GitHub Actions secrets:                          ← (only when Vercel link succeeded)
   https://github.com/<org>/my-store/settings/secrets/actions

   — or —

2. Link to Vercel (when ready):                         ← (when Vercel was skipped)
   cd projects/my-store && vercel link

3. Connect to V0:
   Open https://v0.dev → New project → Connect GitHub repo
   V0 will auto-discover .agents/AGENTS.md for context

4. Start developing:
   cd projects/my-store && yarn dev

Generated structure:

projects/my-store/
├── .env                           # Commerce config (mock by default, live backend optional)
├── .agents/
│   ├── AGENTS.md                  # Entry point for AI agents (V0, Claude Code, OpenCode)
│   ├── context/                   # Architecture, types, API, patterns, rules
│   │   ├── architecture.md
│   │   ├── project-structure.md
│   │   ├── types.md
│   │   ├── commerce-api.md
│   │   ├── patterns.md
│   │   └── rules.md
│   └── skills/                    # Playbooks for repeatable tasks
│       ├── generate-page.md
│       ├── generate-component.md
│       ├── generate-module.md
│       ├── add-commerce-feature.md
│       ├── add-route.md
│       └── audit-changes.md
├── .vercel/
│   └── project.json               # Vercel org/project IDs (when Vercel linked)
├── .github/
│   └── workflows/
│       └── vercel-deploy.yml      # CI/CD deploy workflow (when Vercel linked)
├── package.json                   # @thorprovider/my-store, updated deps
├── app/                           # Next.js 16 app directory
├── components/                    # UI components
├── lib/                           # Commerce config, env, utilities
├── styles/                        # Theme tokens
└── ...

What Gets Generated

package.json

• Name: @thorprovider/<name>
• Dependencies: All workspace:* refs → ^X.Y.Z (pre-baked versions)
• Scripts configured:
  • dev, build, start: Next.js commands
  • type-check: TypeScript validation

.agents/

Contains persistent AI context for V0 and other agents (Claude Code, OpenCode, Cursor, etc.). Inspired by Claude Code's CLAUDE.md + .claude/skills/ and OpenCode's AGENTS.md + .opencode/agents/ patterns.

Structure:

• AGENTS.md — root entry point: what the app is, what agents can/cannot do, read order
• context/ — architecture rules, types, API signatures, patterns, hard constraints (adapted from packages/core/docs/)
• skills/ — playbooks for repeatable tasks (generate-page, generate-component, audit-changes, etc.)

Use --no-context to skip generation.

.env

Copied from .env.example.

• Default: starts in mock mode with no backend required
• Optional: add real provider + backend URL + publishable key to use live commerce data immediately

.vercel/project.json (conditional)

Created when Vercel linking succeeds. Contains orgId and projectId required by vercel CLI and the GitHub Actions workflow. Generated automatically — do not edit manually.

.github/workflows/vercel-deploy.yml (conditional)

Generated when Vercel linking succeeds. Deploys to Vercel on every push to main and posts preview URLs on pull requests.

Required GitHub Actions secrets (printed during scaffolding):

• VERCEL_TOKEN — Vercel Access Token
• VERCEL_ORG_ID — From .vercel/project.json
• VERCEL_PROJECT_ID — From .vercel/project.json

Examples

Create a new storefront in monorepo

cd thor-commerce
yarn create:app --name my-shop
cd projects/my-shop
yarn dev

Scaffold + push to GitHub

# In monorepo root, set .env
export GITHUB_TOKEN=ghp_xxxxx
export GITHUB_ORG=my-org

yarn create:app --name my-shop

# Verify the remote was created
cd projects/my-shop
git remote -v

Create without git or install (for CI/CD)

yarn create:app --name my-shop \
  --skip-git \
  --skip-install

cd projects/my-shop
# ... run custom setup (docker build, etc.)
yarn install

Standalone usage (from outside monorepo)

npx @thorprovider/create-thor-app my-store

cd my-store
# Optional: update .env with live backend settings, or keep mock mode
yarn dev

Troubleshooting

"Cannot find Thor Commerce monorepo"

Cause: Running from outside the monorepo without npx or without the bundled CLI.

Fix: Use npx @thorprovider/create-thor-app or run from within thor-commerce/.

"Directory already exists"

Cause: Output path already exists.

Fix: Choose a different --name or delete the existing directory.

"git init failed"

Cause: Git not installed or not in $PATH.

Workaround: Use --skip-git and initialize manually later.

"GITHUB_TOKEN not set in root .env"

Cause: Trying to create GitHub remote without GITHUB_TOKEN in monorepo .env.

Workaround: Use --skip-remote or set GITHUB_TOKEN and try again.

"VERCEL_TOKEN not set — skipping Vercel integration"

Cause: Trying to link Vercel without VERCEL_TOKEN in monorepo .env or environment.

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).

"yarn install failed — run it manually"

Cause: Missing dependencies or network issues.

Fix:

cd projects/my-store
yarn install

"Node.js version too old"

Cause: Using Node < 18.17.

Fix:

nvm install 18.17.0
nvm use 18.17.0

Development

Build from source

cd packages/create-thor-app
yarn build

This runs tsup which compiles src/ and then bundles packages/core → templates/default/ via the onSuccess hook.

Test locally

# Monorepo mode
node packages/create-thor-app/dist/index.js test-app --skip-install --skip-git

# Check output
ls projects/test-app/

Type-check

yarn workspace @thorprovider/create-thor-app type-check

Watch mode

yarn workspace @thorprovider/create-thor-app dev

Architecture

The package is structured for maintainability:

| File | Purpose | |------|---------| | src/index.ts | CLI entry point (Commander.js) | | src/create-app.ts | Main orchestration logic | | src/types.ts | Shared TypeScript interfaces | | src/helpers/logger.ts | Color logging (zero deps) | | src/helpers/template.ts | Template resolution + copy filter | | src/helpers/package-json.ts | Dependency resolution | | src/helpers/git.ts | Git init + GitHub remote creation | | src/helpers/vercel.ts | Vercel project creation via REST API | | src/helpers/prompts.ts | Shared TTY-aware interactive prompts | | src/helpers/install.ts | Yarn install wrapper | | src/helpers/env.ts | .env creation (accepts backend overrides) | | src/helpers/agents-dir.ts | .agents/ directory generation (AGENTS.md + context/ + skills/) | | tsup.config.ts | Build config + template bundling hook |

How V0 is Programmed for ThorBuilder

ThorBuilder does not rely on a single prompt. V0 is guided through multiple aligned mechanisms that must stay in sync as the codebase evolves.

Guardrail Layers

1. Template .agents/AGENTS.md

   • Compact mission, architecture, runtime, and conflict-resolution rules
   • Used as project-level instructions and persisted for later chat injection

2. Template docs (templates/default/docs/)

   • types.md → domain contracts
   • commerce-api.md → all allowed commerce.* methods
   • patterns.md → canonical implementation patterns
   • rules.md → non-negotiable constraints
   • project-structure.md → file ownership and boundaries
   • decision-matrix.md → fast architecture decisions when prompts create pressure to drift

3. Validator rules (templates/default/ai-validator.json)

   • Regex-based post-generation checks that catch architectural drift
   • Examples: backend SDK imports, raw backend fetches, env gating, alternate backend stacks

4. Dynamic ThorBuilder prompt injection

   • thor-commerce-builder/lib/thor-context.ts injects project config, guardrail policy, and backend guidance at chat time
   • Mode-aware: mock, incomplete real backend config, or live backend configured

Core Programming Rules for V0

• Build a ThorCommerce storefront, not a generic web app
• Use commerce.* only for backend access in starter/app code
• Never integrate vendors directly via SDKs or raw fetch in L5
• Respect mock-first / live-immediate runtime behavior
• Live backend data is authoritative when configured and available
• Demo fixtures are allowed only for presentation-oriented sections in mock/incomplete mode

Maintenance Rule

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.

See also:

• V0_GUARDRAILS_MAINTENANCE.md
• templates/default/docs/decision-matrix.md

Dual-mode detection

findMonorepoRoot() walks up the directory tree looking for packages/core/package.json:

• Found → Monorepo mode (copy live, resolve deps at runtime)
• Not found → Standalone mode (use templates/default/, use pre-baked versions)

Publishing

This package is published publicly to npm through the monorepo Changesets workflow:

yarn changeset
# open and merge your PR to main
# CI versions and publishes on push to main

Include @thorprovider/create-thor-app in a changeset whenever you change the CLI, its bundled template, or any publishable behavior consumers depend on.

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.

License

MIT — See root LICENSE file.

Support

• Issues: Report in https://github.com/thorprovider/thor-commerce/issues with label create-thor-app
• Questions: Ask in internal Slack or GitHub Discussions
• Docs: Read /packages/core/docs/ for template architecture