Commands

Overview

This page documents all available npm scripts and CLI commands for development, database management, routing, testing, and deployment.

Development Commands

Start Development Server

npm run dev

Starts the Next.js development server with:

• Turbopack for fast refresh
• Hot module replacement (HMR)
• Declarative routing watch mode (automatically rebuilds routes on page changes)
• Server runs on http://localhost:3000

Build for Production

npm run build

Creates an optimized production build:

• Compiles TypeScript
• Bundles and minifies JavaScript/CSS
• Optimizes images and assets
• Generates static pages
• Uses Turbopack for faster builds

Run this before deploying or to test production behavior locally.

Start Production Server

npm run start

Starts the production server after running npm run build. Used for testing production builds locally before deployment.

Database Commands

Push Schema Changes

npm run db:push

Use this for development. Pushes your schema changes directly to the database without creating migration files:

• Syncs src/db/tables/*.ts with database
• Fast iteration during development
• No migration history
• Can cause data loss if not careful

When to use:

• During active development
• After creating/modifying tables in src/db/tables/
• When you want instant schema updates

Generate Migration

npm run db:generate

Generates SQL migration files from schema changes:

• Creates migration file in src/db/migrations/
• Compares current schema with database
• Generates SQL statements for changes
• Safe for production use

When to use:

• Before deploying to staging/production
• When you want version-controlled schema changes
• To review SQL before applying

Run Migrations

npm run db:migrate

Applies pending migrations to the database:

• Executes SQL files from src/db/migrations/
• Tracks applied migrations
• Safe, reversible schema changes

When to use:

• Deploying to staging/production
• After pulling migration files from git
• Setting up a new environment

Database Studio

npm run db:studio

Opens Drizzle Studio in your browser (http://localhost:4983):

• Visual database browser
• View and edit table data
• Run queries
• Inspect schema

When to use:

• Debugging data issues
• Manually editing records
• Exploring database structure

Routing Commands

Build Routes

npm run dr:build

Builds declarative routing configuration:

• Scans src/app/[locale]/ for pages
• Reads page.info.ts files for metadata
• Generates src/routes/index.ts with type-safe routes
• Creates route helpers (PageName(), <PageName.Link />)

When to use:

• After creating new pages
• After modifying route metadata
• Before committing routing changes

Build Routes (Watch Mode)

npm run dr:build:watch

Continuously watches for changes and rebuilds routes automatically:

• Monitors src/app/[locale]/ directory
• Auto-rebuilds on page/metadata changes
• Runs automatically with npm run dev

Type Checking & Linting

Type Check

npm run type-check

Runs TypeScript compiler in check mode:

• Validates all TypeScript files
• Reports type errors
• Does not emit JavaScript
• Checks entire project

When to use:

• Before committing code
• In CI/CD pipelines
• After major refactors

Lint Code

npm run lint

Runs ESLint to check code quality:

• Identifies code style issues
• Reports potential bugs
• Enforces project conventions
• Includes Next.js-specific rules

When to use:

• Before committing code
• To find potential issues
• To enforce code standards

Email Development

Email Dev Server

npm run email:dev

Starts the React Email development server:

• Preview email templates at http://localhost:3001
• Hot reload for email changes
• Test email designs
• Inspect HTML output

When to use:

• Creating new email templates
• Designing email layouts
• Testing email rendering
• Previewing localized emails

Command Reference Table

Development Workflow

Daily Development

# Start development
npm run dev

# In another terminal, if needed
npm run db:studio

After Schema Changes

# During development
npm run db:push

# For production
npm run db:generate
npm run db:migrate

Before Committing

# Check types
npm run type-check

# Lint code
npm run lint

# Build to ensure no errors
npm run build

Deploying to Production

# Generate migrations
npm run db:generate

# Commit migrations
git add src/db/migrations
git commit -m "Add migration for <feature>"

# Build and test locally
npm run build
npm run start

# Deploy (Vercel, etc.)
git push

Troubleshooting

Dev Server Won't Start

1. Check if port 3000 is already in use
2. Verify DATABASE_URL in .env.local
3. Delete .next folder and restart: rm -rf .next && npm run dev

Database Push Fails

1. Verify database is running
2. Check DATABASE_URL format: postgresql://user:pass@host:port/db
3. Ensure database exists
4. Check for conflicting schema changes

Type Errors After Route Changes

1. Run npm run dr:build to regenerate routes
2. Restart TypeScript server in VS Code (Cmd/Ctrl + Shift + P → "Restart TypeScript Server")

Build Fails

1. Run npm run type-check to see type errors
2. Run npm run lint to see linting errors
3. Check for missing environment variables
4. Clear .next folder: rm -rf .next

Next Steps

• Best Practices - Learn development conventions
• AI Agents - Set up AI coding assistants
• Templates - Step-by-step task guides