create-codewave-app

A CLI that scaffolds opinionated, production-ready Next.js applications. Composes Next 16 + tRPC + TanStack Query + Tailwind v4 + shadcn/ui + Prisma 7

• Better Auth + Resend into a working codebase that builds cleanly on the first try.

Quick start

# Interactive (walks you through prompts)
npx create-codewave-app@latest my-app

# Non-interactive (flag-driven, suitable for CI)
npx create-codewave-app@latest my-app \
  --db prisma-postgres \
  --auth better-auth \
  --auth-plugins 2fa,google,github \
  --email \
  --pm pnpm \
  --src-dir \
  --install \
  --git \
  --yes

Both modes produce identical output. --yes skips all confirms and uses defaults for any unspecified flag.

What you get

A Next.js 16 App Router project with:

Layer	Technology
Runtime	Next 16, React 19, TypeScript (strict)
Styling	Tailwind v4 (via @tailwindcss/postcss), shadcn/ui baseline
API	tRPC v11, TanStack Query v5, superjson
Database	Prisma 7 with prisma-client generator (optional)
Auth	Better Auth 1.x (optional, with plugins)
Email	Resend + React Email (optional)
Tooling	ESLint flat config, Prettier-friendly

Every combination is covered by a scaffold integration test suite that verifies generated file structure, dependency lists, and generated content. End-to-end build smoke tests (install + next build) are run manually before each release.

Features (the things you can mix in)

• --db prisma-postgres — Prisma 7 + @prisma/adapter-pg + pg. Connection via DATABASE_URL.
• --db prisma-sqlite — Prisma 7 + @prisma/adapter-better-sqlite3 + better-sqlite3. DATABASE_URL="file:./dev.db" by default.
• --auth better-auth — Better Auth wired to your Prisma db. Sign-in, sign-up, forgot-password, reset-password, verify-email, and a protected dashboard. Adds protectedProcedure to tRPC.
• --auth-plugins 2fa — Two-factor (TOTP / email OTP / backup codes) page + form. Extends the Prisma User model and adds a TwoFactor model automatically.
• --auth-plugins google,github — Social OAuth providers. Each adds *_CLIENT_ID / *_CLIENT_SECRET env vars.
• --email — Resend + React Email templates for verification, password reset, and OTP. When auth is selected without email, a stub lib/email.ts is emitted so the build still works.

CLI flags

Flag	Values	Default
[name] (positional)	., a name, or any path	(prompt)
--db	prisma-postgres, prisma-sqlite, none	prompt
--auth	better-auth, none	prompt
--auth-plugins	csv of 2fa, google, github	none
--storage	none	none
--email / --no-email	boolean	prompt
--src-dir / --no-src-dir	boolean	true
--pm	npm, pnpm, yarn	auto-detect
--install / --no-install	boolean	true
--git / --no-git	boolean	true
-y / --yes	flag	false

Project name forms

The positional argument can be any of:

• . — scaffold into the current directory (must be empty or contain only .git)
• my-app — scaffold into ./my-app
• foo/my-app — scaffold into ./foo/my-app (creates the parent)
• /abs/path/my-app — scaffold into the absolute path
• C:\Users\me\my-app — Windows path, same idea

The basename always becomes the name in the generated package.json.

Next steps after scaffold

cd my-app
cp .env.example .env.local        # fill in secrets
pnpm install                       # if --no-install
pnpm exec prisma generate          # if you picked Prisma
pnpm exec prisma db push           # create your schema
pnpm dev                           # start the dev server

Contributing

The architecture is documented in progress-tracker.md. Adding a new feature is one folder under src/features/<category>/<id>/ plus one line in src/core/registry.ts and one matrix entry. See any existing feature (prisma-postgres is the simplest) for the pattern.

git clone <repo>
cd create-codewave-app
pnpm install
pnpm typecheck
pnpm lint
pnpm test            # unit tests
pnpm test:scaffold   # integration: scaffold + assert into tempdirs

License

MIT.