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

create-thor-app

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

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 \
  --preset electro \
  --site-url https://my-store.com \
  --generate-regions

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

# With site configuration
yarn create:app --name my-store \
  --preset electro \
  --site-url https://my-store.com

# 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

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
• scripts/generate-regions-config.ts is bundled in the standalone template

Environment (for standalone):

export NODE_AUTH_TOKEN=ghp_xxxxx  # For GitHub Packages .npmrc

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 (medusa, shopify) → .env | medusa | | --commerce-api-url <url> | Backend API URL → .env | http://localhost:9000 | | --commerce-api-key <key> | Publishable API key → .env | placeholder | | --preset <preset> | Visual preset → site.config.ts | electro | | --site-url <url> | Public site URL → site.config.ts | https://example.com | | --generate-regions | Run region generation from backend after install | false | | --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. Configure your 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                           # Backend config (copy from .env.example)
├── .npmrc                         # GitHub Packages auth (included)
├── .agents/
│   ├── AGENTS.md                  # Entry point for AI agents (V0, Claude Code, OpenCode)
│   ├── context/                   # Architecture, types, API, patterns, rules
│   │   ├── architecture.md
│   │   ├── project-structure.md
│   │   ├── dependencies.md
│   │   ├── components.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 provider, config, utilities
├── scripts/                       # generate-regions-config.ts (bundled)
└── ...

What Gets Generated

package.json

• Name: @thorprovider/<name>
• Dependencies: All workspace:* refs → ^X.Y.Z (pre-baked versions)
• Scripts configured:
  • prebuild / predev: Runs region generation
  • dev, build, start: Next.js commands
  • generate:regions: Region config generator

.npmrc

GitHub Packages registry config. Uses NODE_AUTH_TOKEN ENV for authentication.

.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. Update with your Medusa backend URL before running yarn dev.

.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
• NODE_AUTH_TOKEN — GitHub PAT with read:packages (for @thorprovider/*)

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)

# Requires NODE_AUTH_TOKEN set
npx @thorprovider/create-thor-app my-store

cd my-store
# Update .env with backend URL
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).

"Region generation failed"

Cause: --generate-regions could not connect to the backend (timeout, wrong URL, wrong API key).

Behavior: The scaffold does not fail. A fallback English-only regions-config.ts is generated automatically.

Fix: Verify credentials in .env, then run:

cd projects/my-store
yarn generate:regions

"--generate-regions skipped: requires dependencies"

Cause: --generate-regions was used together with --skip-install.

Fix: Install dependencies first, then run region generation manually:

yarn install && yarn generate:regions

"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 + .npmrc creation (accepts overrides for backend flags) | | src/helpers/site-config.ts | Patches config/site.config.ts with --preset / --site-url | | src/helpers/agents-dir.ts | .agents/ directory generation (AGENTS.md + context/ + skills/) | | tsup.config.ts | Build config + template bundling hook (copies regions script) |

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

The package is published to GitHub Packages with publishConfig.access = "restricted":

yarn changeset
yarn version-packages
yarn ci:publish

Only include @thorprovider/create-thor-app in changesets if publishing this package alone.

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