Stackr

Scaffold a runnable full-stack Next.js project in one command. Stackr assembles a base Next.js app and composes feature "installers" (database, ORM, auth, styling, pre-built interfaces) into a coherent, immediately bootable project.

npm create stackrjs@latest my-app

Published on npm as create-stackrjs. A web configurator lets you pick a stack and copy the exact command.

What you get

Stackr composes a single coherent, runnable stack from your choices:

| Dimension | Options | | --------- | ------- | | Architecture | Monolith (single Next.js App Router app, TypeScript strict) — or microservices (web + Hono API + nginx gateway, npm workspaces) | | Database | PostgreSQL, MySQL or MongoDB (via bundled docker-compose.yml) | | ORM | Prisma 7 or Drizzle (SQL), or Mongoose (MongoDB) | | Auth | NextAuth / Auth.js v5, Better Auth, Clerk or Supabase Auth | | Styling | Tailwind CSS or shadcn/ui | | Interfaces | Auth portal (login / register / forgot / reset + /account), user dashboard, admin / back-office, landing page |

The generated app boots with:

docker compose up -d
npm install
npx prisma migrate dev --name init
npm run dev

Usage

npm create stackrjs@latest [name] -- [options]
# or:  npx create-stackrjs [name] [options]

  --architecture <a>   monolith   | microservices
  --database <db>      postgres   | mysql | mongodb
  --orm <orm>          prisma     | drizzle | mongoose
  --auth <auth>        nextauth   | better-auth | clerk | supabase
  --styling <s>        tailwind   | shadcn   (shadcn ships the full Tailwind stack)
  --interfaces <list>  auth-pages,dashboard,admin,landing
  -y, --yes            skip the wizard, use flags + defaults
  --ci                 non-interactive: implies --yes --no-install --no-git
  --no-install         skip npm install
  --no-git             skip git init

Run with no options for an interactive wizard (@clack/prompts).

Compatible by construction

The dimensions are linked, so you can't assemble an incompatible stack. Picking a technology constrains the rest (MongoDB rules out Drizzle; Supabase Auth needs Postgres; shadcn implies Tailwind). Incompatible flag combinations are rejected with a clear message, and both the wizard and the web configurator grey out options that clash with your current choices or aren't generatable yet. The catalogue + rules live in one place — src/shared/registry.ts — consumed by the CLI and mirrored into the web app.

How it works

Stackr is composition over templating. A template/base Next.js app is copied, then each selected installer (src/installers/*) contributes:

1. files copied from template/extras/<feature> into the project,
2. dependencies / scripts pushed onto a shared package.json draft,
3. environment variables pushed onto a shared .env accumulator.

The orchestrator (src/helpers/scaffoldProject.ts) merges and writes everything once at the end. Adding a new option = add a template/extras/<x> folder + an installers/<x>.ts and register it — no engine changes. This is the create-t3-app model.

Web configurator

web/ is a Next.js app (deployable to Vercel) that lets users pick a stack and copy the matching create-stackrjs command (npm / pnpm / yarn / bun).

cd web
npm install
npm run dev      # http://localhost:3000

The configurator reads the same option catalogue + compatibility rules as the CLI. web/src/lib/stack.ts is a mirror of src/shared/registry.ts (the deployable Next app imports no TypeScript from the engine); the test/registry-sync.test.ts suite fails if the two ever drift, so the registry stays the single source of truth.

Develop Stackr

npm install
npm run build      # bundle the CLI with tsup -> dist/
npm run typecheck  # type-check the engine
npm run smoke      # generate every stack and verify each installs + builds
node dist/index.js demo --ci   # try it locally

Testing

Vitest suites live in test/ (engine) and web/test/ (configurator):

npm test            # engine: flags, selections, package.json/env merge, installers,
                    # plus an integration test that scaffolds a project to a temp dir
npm run smoke       # heavier: generate each stack (monolith, shadcn, microservices),
                    # then npm install, tsc and build the output
cd web && npm test  # the command builder

CI/CD & automated releases

Two GitHub Actions workflows:

• .github/workflows/ci.yml — on every push/PR: typecheck, test and build the CLI (Node 18/20/22) and the web app.
• .github/workflows/release.yml — on push to main: runs the checks, then semantic-release versions, publishes to npm (with provenance), tags, writes CHANGELOG.md and creates a GitHub Release — fully automatic, no manual version bumps.

The version is derived from your commit messages (Conventional Commits):

| Commit prefix | Release | | ------------- | ------- | | fix: ... | patch (1.2.3) | | feat: ... | minor (1.3.0) | | feat!: ... or BREAKING CHANGE: in body | major (2.0.0) | | chore:, docs:, test:, refactor: ... | no release |

One-time setup

1. Create the repo on GitHub and push main.
2. Add an NPM_TOKEN secret (npm → Access Tokens → Automation token) under Settings → Secrets and variables → Actions. GITHUB_TOKEN is provided automatically.

That's it — from then on, just commit with the right prefix and merge to main. The published tarball is limited to dist/ + template/ (files in package.json; verify with npm pack --dry-run).

Roadmap

Every dimension above ships at least two generatable options today. Next up: OAuth providers for the credentials stacks, third-party services (Stripe, Resend, …), more API styles and additional architectures. Each new option is a template/extras/<x> folder plus an installers/<x>.ts registered in src/shared/registry.ts — the installer engine absorbs them without a rewrite.