FAQ

Why Turborepo and not Nx?

Turborepo is intentionally simpler than Nx. It does one thing — orchestrate tasks across a pnpm workspace with caching — and does it well. Coldstart's philosophy is to use the most boring, widely-adopted tool for each job so users can find answers on Stack Overflow and GitHub instead of vendor-specific docs.

Nx is more powerful (plugin ecosystem, code generators, project graphs), but most of its features overlap with what Coldstart already handles: scaffolding is done at generation time, not via Nx executors. For the generated monorepo, Turborepo's pipeline + pnpm workspaces cover 95% of needs with 10% of the complexity.

If you need Nx-specific features (computation caching across a team via Nx Cloud, for example), you can migrate a generated project to Nx — the underlying pnpm workspace is standard.

Why Hono and not Next.js API routes?

Three reasons:

1. Portability — Hono runs on Node, Bun, Cloudflare Workers, Deno, and Vercel. If you later decide to deploy your API outside Vercel, the code moves without changes. Next.js API routes are locked to the Next.js runtime.
2. OpenAPI first — Hono has native integration with @hono/zod-openapi, which means your API gets typed clients, an OpenAPI schema, and a Scalar/Swagger UI for free. Getting the same quality with Next.js API routes requires a lot of manual wiring.
3. Separation of concerns — a dedicated API app keeps the mobile client happy (it can hit a stable URL without going through Next.js middleware), and allows deploying the API independently (its own Docker image, its own scaling).

Why both Polar and Stripe?

They solve different problems:

• Stripe is the industry standard for payment processing, but you're responsible for VAT/sales tax collection, invoicing, and compliance.
• Polar is a merchant of record (MoR) — they handle VAT, sales tax, and compliance globally. Simpler to start with, but less flexible (fewer payment methods, fewer countries, higher fees).

Coldstart supports both because the right choice depends on your market, your team's legal setup, and your monetization model. For a solo founder shipping globally, Polar is usually the fastest path to revenue. For a larger team that already has legal/finance support, Stripe gives more control.

Can I use Coldstart in production?

Yes. Coldstart generates real, fully-wired projects — not throwaway templates. Everything it produces is code you own, with no runtime dependency on Coldstart itself. Once the project is scaffolded, you can delete the .coldstart.json file and the CLI has no further role in your app.

That said, the generated code is a starting point, not a finished product. You'll need to:

• Review the domain guidelines injected into CLAUDE.md and adjust to your business rules.
• Set up real infrastructure (Neon database, Resend API key, billing provider keys, OAuth apps).
• Customize the UI, copy, and branding to match your product.
• Add the business logic specific to your app.

The scaffolding handles the boilerplate (auth, billing webhooks, env validation, CI, tests) — not the product.

How do I add a platform to an existing project?

Use coldstart add:

pnpm dlx @yabbal/coldstart add mobile

Available modules: web, mobile, desktop, api, admin, analytics, i18n, multi-tenant.

This runs the relevant generator against your existing .coldstart.json, applies the necessary patches, and installs dependencies. Always commit your current work before running it — the patches modify files in apps/ and packages/.

How do I upgrade between Coldstart versions?

Coldstart itself does not maintain your project after scaffolding. Upgrading Coldstart only affects new projects — existing projects are not rescaffolded.

If you want to pick up improvements from a newer Coldstart version in an existing project, two options:

1. Cherry-pick — scaffold a new project with the same .coldstart.json using coldstart replay .coldstart.json -o /tmp/fresh, then manually diff and copy what you want.
2. Re-run coldstart add — if the improvement relates to a specific module (e.g. analytics), re-run coldstart add analytics against your existing project.

For generator-level changes (new CI workflows, updated CLAUDE.md, new skills), option 1 is usually faster.

How do I customize the generated CLAUDE.md?

CLAUDE.md is generated once at scaffold time and committed to your repo. After that, it's yours — edit it freely. Common customizations:

• Add company-specific conventions (code review policies, naming rules, git workflow).
• Document business rules that can't fit into the domain presets.
• Add links to internal tools, Notion pages, design system docs.
• Adjust the "Stack" section if you replaced a library (e.g. migrated from Drizzle to Prisma).

When Claude Code starts a session in the project, it automatically reads CLAUDE.md, so every edit you make takes effect immediately.

If you want Coldstart to regenerate CLAUDE.md from scratch (and lose your edits), you can delete it and run coldstart setup.

Can I use a different package manager?

No. Coldstart is opinionated: pnpm only. The generator uses pnpm workspaces, pnpm dlx, workspace:* protocols, and the pnpm-workspace.yaml config. Converting the output to npm or yarn is not supported and would require manual work across every package.json.

This is a deliberate constraint — maintaining 3 package manager variants would double the test surface and fragment the community.

Is Coldstart open source?

Yes, under the MIT license. Source on GitHub.

The generated projects are 100% yours — no license on the output, no attribution requirement.

How does the Claude Code skill work?

Coldstart is also distributed as a Claude Code skill. Install it with:

pnpm dlx skills add yabbal/cold-start

Then in Claude Code, type /coldstart and describe your project in plain language. The skill guides Claude through the CLI flow, makes sensible defaults based on your description, and handles the pnpm install + git init automatically.

See the Claude Code guide for details.