create-nextspark-app

Create a new NextSpark SaaS project with a single command.

Usage

npx create-nextspark-app my-app

This will:

1. Create a new directory my-app
2. Install @nextsparkjs/core
3. Run the interactive setup wizard
4. Generate your project with all configurations

Options

# Interactive setup (default)
npx create-nextspark-app my-app

# Use a preset to skip some prompts
npx create-nextspark-app my-app --preset saas
npx create-nextspark-app my-app --preset blog
npx create-nextspark-app my-app --preset crm

# Pick a template (starter is stable; blog, crm and productivity are experimental)
npx create-nextspark-app my-app --theme starter

# Skip all prompts (use defaults)
npx create-nextspark-app my-app -y

Experimental: the blog, crm and productivity templates, the first-party plugins (--plugins), and billing (Stripe, Polar) are not part of the stable 1.0 surface and may change without a deprecation period. The CLI says so when you select them.

What's Included

• Next.js 16 with App Router and Turbopack by default
• TypeScript strict configuration
• Tailwind CSS v4 with CSS-based theming
• Authentication ready with Better Auth
• Database setup with PostgreSQL + Drizzle
• UI Components 50+ components based on shadcn/ui
• Entity System with automatic CRUD and APIs
• Page Builder with blocks
• Testing with Jest + Cypress
• i18n with next-intl

After Creation

cd my-app
# set DATABASE_URL in .env (BETTER_AUTH_SECRET is already generated)
pnpm db:migrate
pnpm dev

pnpm build stops until a sign-in provider can work in production: set RESEND_API_KEY and RESEND_FROM_EMAIL (and/or GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET) in .env, or declare that your host injects them with NEXTSPARK_AUTH_RUNTIME_ONLY=email,google pnpm build. pnpm dev needs none of this.

Installing with lifecycle scripts disabled (pnpm install --ignore-scripts) works: nothing a project needs is created at install time, and pnpm dev and pnpm build generate src/app and the registries first (pnpm build:registries does only that). Cypress downloads its binary during install; with scripts off, run pnpm exec cypress install before pnpm cy:run.

After pnpm install --frozen-lockfile --ignore-scripts, the whole sequence is pnpm db:migrate, then pnpm dev, or pnpm build and pnpm start. @nextsparkjs/core's own postinstall only prints a notice about a committed src/app.

Requirements

• Node.js 22.14.0 or later
• pnpm 10 (10.34.6 or later), 11 or 12. npm, yarn and bun are not supported (pnpm 9 is only for contributing to the NextSpark repository) Corepack bundled with Node.js 22.x cannot install pnpm 12: update Corepack first (npm install --global corepack@latest) or install pnpm standalone (curl -fsSL https://get.pnpm.io/install.sh | sh -); Node.js 24 ships a Corepack that can. The floor is 10.34.6 because pnpm 10.16 fails on a warm store cache with ERR_PNPM_MISSING_TIME.

Installing with another pnpm than the one that created the project

When changing pnpm major versions, update the project's packageManager field to that major first so Corepack permits the command. Corepack needs Node.js 22.14.0 or later to download pnpm: Corepack in Node.js 22.13.x fails with Cannot find matching keyid. A lockfile written by pnpm 9 or 10 can then contain a dependency that pnpm 11 refuses during its first day after publication; regenerate that lockfile with pnpm clean --lockfile and pnpm install.

pnpm 11 checks every version in pnpm-lock.yaml against a minimum release age of one day each time it installs, and refuses the lockfile with ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION if any of them was published less than a day before. The project's pnpm-workspace.yaml declares that same policy, so what each pnpm locks when it creates the project is:

| Created with | Locks | Installs later with pnpm 11 | |---|---|---| | pnpm 11 | versions at least a day old | yes | | pnpm 10.16 or later | versions at least a day old | yes | | pnpm 9, or pnpm 10 before 10.16 | the newest version each range allows | only once every locked version is a day old |

For the last row, either wait until the day has passed, or let pnpm 11 resolve the project again under the policy:

pnpm clean --lockfile
pnpm install

pnpm 10 has no lenient mode for a pinned version younger than a day, so the project excludes the NextSpark packages (every @nextsparkjs/* package and create-nextspark-app) by name: a NextSpark release installs on the day it is published, on pnpm 10.16 and later, 11 and 12. Every other dependency keeps the one-day wait.

Documentation

Visit nextspark.dev/docs for full documentation.

License

MIT