Common Commands

A practical reference for daily development, tests and local services.

Use these commands from the repository root. They are defined in package.json, so prefer them over running the underlying tools directly.

Everyday Development

Command	Purpose
`npm install`	Install project dependencies
`npm run dev`	Start the Next.js development server on port 3000
`npm run build`	Create a production build
`npm run start`	Serve an existing production build
`npm run typecheck`	Check TypeScript without emitting files

Environment-aware commands

Next.js loads the root .env file for dev, build and start. The test scripts use the repository's with-dev-env wrapper because Vitest and Playwright also need those values outside the Next.js process:

Terminal

npm run with-dev-env -- <command>

You normally do not need to call this wrapper yourself. Use it when running a one-off tool that imports application modules depending on lib/env.ts.

Code Quality

Command	Purpose
`npm run format`	Check formatting with Oxfmt
`npm run format:write`	Apply safe formatting changes
`npm run lint`	Check lint rules with Oxlint
`npm run lint:write`	Apply safe lint fixes
`npm run check`	Run Oxlint and Oxfmt checks together

Run the non-writing commands in CI. Review the diff after any command ending in :write before committing its changes.

Tests

Command	Purpose
`npm run test -- --run`	Run the unit test suite once and exit
`npm run test:watch`	Run unit tests in watch mode
`npm run test:coverage`	Run unit tests and collect coverage
`npm run test:db`	Include tests that require the configured test database
`npm run test:e2e:setup`	Install the Playwright browser
`npm run test:e2e`	Run Playwright end-to-end tests headlessly
`npm run test:e2e:headed`	Run Playwright while displaying the browser
`npm run test:e2e:ui`	Open Playwright's interactive test runner
`npm run test:e2e:debug`	Run Playwright with its inspector
`npm run e2e:ci`	Install Playwright browsers and run E2E tests for CI

test:db and the Playwright commands load variables from the root .env file. Use isolated test credentials and never point them at production services.

Running npm run test without -- --run can enter Vitest's interactive watch workflow in a local terminal. Use the explicit one-shot command in scripts and before commits so the process exits with a reliable status.

Local Services

Command	Purpose
`npm run docker:up`	Start the included PostgreSQL container
`npm run docker:down`	Stop the included containers
`npm run docker:logs`	Follow container logs
`npm run db:studio`	Open the Drizzle database browser
`npm run stripe:listen`	Forward Stripe CLI events to the local webhook
`npm run stripe:trigger -- <event>`	Ask Stripe CLI to emit a test event
`npm run email:dev`	Preview React Email templates on port 3001

Database migration commands differ between the starter kit variants. Follow the Drizzle database guide before changing or applying a schema.

Drizzle database commands

Use these repository scripts instead of calling the underlying tools directly.

Generate a migrationnpm run db:generate

Regenerate migrations from origin/mainnpm run db:regenerate

Apply committed migrationsnpm run db:migrate

Push schema changes without a migrationnpm run db:push

Open Drizzle Studionpm run db:studio

Repository MCP server

Command	Purpose
`npm run mcp:build`	Compile the local read-only MCP server
`npm run mcp:start`	Compile and start the MCP server over standard I/O

An MCP client normally launches mcp:start for you. The process waits for MCP messages over standard input/output; it does not open a browser page or HTTP port. See the MCP server guide for the checked-in configuration and client-specific setup.

Dependency Maintenance

Command	Purpose
`npm run deps:check`	List dependency updates without changing files
`npm run deps:update`	Update version ranges in `package.json`

After updating dependencies, run npm install, review the lockfile and complete the typecheck, lint, test and production build checks before committing.

Be careful with the clean command npm run clean removes generated output, dependencies and ignored files from the listed build directories. Commit or back up any ignored work you intend to keep before running it.