create-flash-stack

Start a new app with Next.js App Router, Convex, Better Auth, TanStack Query/Form, Effect, Motion, Resend, Tailwind, and Oxlint/Oxfmt, then build your product on top.

Requirements

Use Node.js 24 LTS (24.11+), or Node 22.18+/26+, and Bun 1.4.2. Bun installs the generated app even when the CLI is launched with npm or pnpm.

bun create flash-stack my-app
# Or: npx create-flash-stack@latest my-app
# Or: pnpm create flash-stack my-app

• --no-install skips dependency installation; install Bun and run bun install --frozen-lockfile later.
• --no-git skips Git initialization and the initial commit.
• --help / --version print CLI information.

The destination must be empty. Without a directory, an interactive terminal prompts for one. Scaffolding never links or deploys a Convex project. Follow the generated SETUP.md for the install → configure → build path. The auth schema, including its rate-limit table, is already included. You select a development Convex backend and supply the frontend URLs and auth/email credentials before using the auth flows.

The starter includes sign-up/sign-in/sign-out, verified email and password recovery, an account page, reusable loading/error/empty states, a local setup checker, and CI. The separate example form demonstrates validation only. Configure the backend and email provider, then verify hosted flows before releasing an app.

Local development and verification

bun install --frozen-lockfile
bun run check
bunx playwright install chromium
bun run check:release
node dist/cli.mjs /tmp/my-flash-app --no-git

check runs zero-warning CLI lint, typechecking, build, package lint, and tests. The tests pack the CLI, install the tarball into a temporary consumer, and exercise all install/Git flag combinations. They require Node, npm, Bun, Git, and registry access. Generated apps include their own lint, typecheck, test, format, and build commands. check:release also packs a fresh CLI, generates and builds an app, and runs desktop and mobile Chromium tests. Auth transport is synthetic in browser tests; local core tests exercise Better Auth with an in-memory database. It never provisions a backend or sends email. Use FLASH_STACK_CHROMIUM_PATH to select an existing Chromium binary. Logs and screenshots are written to the ignored .artifacts/ directory.

Upgrade evidence and proposed additions records dependency versions, compatibility decisions, validation limits, and suggestions for review. Auth, setup and CI evidence describes the approved follow-up.

Package maintenance

dist/ and templates/ are included in the package. Rebuild before npm pack. Whenever template dependencies change, regenerate templates/base/bun.lock from a freshly generated app and restore its {{PACKAGE_NAME}} placeholder. Verify a frozen install and the shipped patch before updating either manifest.

Publishing is a separate release action; local checks do not publish anything.