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.