Local Development

This page covers the tools and workflows you’ll use day-to-day while building on NuxtBase.

Dev Server

pnpm dev

npm run dev

yarn dev

The Nuxt dev server starts at http://localhost:3000 with HMR enabled. Changes to pages, components, composables, and server routes are reflected immediately.

Common Scripts

Script	What it does
`pnpm dev` / `npm run dev` / `yarn dev`	Start development server
`pnpm build` / `npm run build` / `yarn build`	Build for production
`pnpm preview` / `npm run preview` / `yarn preview`	Preview production build locally
`pnpm db:generate` / `npm run db:generate` / `yarn db:generate`	Generate a new Drizzle migration
`pnpm db:migrate` / `npm run db:migrate` / `yarn db:migrate`	Apply pending migrations
`pnpm db:studio` / `npm run db:studio` / `yarn db:studio`	Open Drizzle Studio (browser UI)
`pnpm email:debug` / `npm run email:debug` / `yarn email:debug`	Render or send a debug email
`pnpm admin:grant-platform-admin` / `npm run admin:grant-platform-admin` / `yarn admin:grant-platform-admin`	Grant admin role to a user
`pnpm lint` / `npm run lint` / `yarn lint`	Run ESLint
`pnpm lint:fix` / `npm run lint:fix` / `yarn lint:fix`	Auto-fix ESLint issues
`pnpm format` / `npm run format` / `yarn format`	Format with Prettier
`pnpm format:check` / `npm run format:check` / `yarn format:check`	Check formatting only
`pnpm typecheck` / `npm run typecheck` / `yarn typecheck`	Run Nuxt TypeScript checker
`pnpm test` / `npm run test` / `yarn test`	Run Vitest unit tests
`pnpm test:watch` / `npm run test:watch` / `yarn test:watch`	Run Vitest in watch mode
`pnpm test:e2e` / `npm run test:e2e` / `yarn test:e2e`	Run Playwright E2E tests

See package.json for the full list of scripts.

Email Testing

NuxtBase supports three email drivers, controlled by NUXT_MAIL_DRIVER:

Preview (Default)

NUXT_MAIL_DRIVER=preview

Emails are rendered as HTML and saved to .tmp/email-previews/. No SMTP server needed. Open the HTML files in your browser to review.

Mailpit (Recommended for Local)

Mailpit is a local SMTP server with a web UI — the best option for testing email delivery locally.

Docker
Homebrew

docker run -d --name mailpit -p 8025:8025 -p 1025:1025 axllent/mailpit

brew install mailpit
mailpit

Then set in .env:

NUXT_MAIL_DRIVER=smtp
NUXT_SMTP_HOST=127.0.0.1
NUXT_SMTP_PORT=1025
NUXT_SMTP_SECURE=false

View emails at http://localhost:8025.

Debug Email Script

Render a specific email template without triggering the actual flow:

# Render to preview file
pnpm email:debug -- --template verify-email

# Send to a real address via the configured driver
pnpm email:debug -- --template verify-email --send --to you@example.com

# Render to preview file
npm run email:debug -- --template verify-email

# Send to a real address via the configured driver
npm run email:debug -- --template verify-email --send --to you@example.com

# Render to preview file
yarn email:debug --template verify-email

# Send to a real address via the configured driver
yarn email:debug --template verify-email --send --to you@example.com

Available templates: verify-email, reset-password, organization-invitation, subscription-change, credits-alert, magic-link.

Stripe CLI (Webhook Testing)

To test Stripe webhooks locally, install the Stripe CLI and forward events to your dev server:

stripe listen --forward-to localhost:3000/api/billing/webhook

The CLI prints a webhook signing secret (whsec_...). Set it in .env:

NUXT_STRIPE_WEBHOOK_SECRET=whsec_...

Database Workflow

When you change a Drizzle schema file in server/database/schema/:

# 1. Generate a migration from your schema changes
pnpm db:generate

# 2. Apply the migration
pnpm db:migrate

# 1. Generate a migration from your schema changes
npm run db:generate

# 2. Apply the migration
npm run db:migrate

# 1. Generate a migration from your schema changes
yarn db:generate

# 2. Apply the migration
yarn db:migrate

To browse your database:

pnpm db:studio

npm run db:studio

yarn db:studio

This opens Drizzle Studio at https://local.drizzle.studio.

If https://local.drizzle.studio refuses to connect or your browser does not trust the local certificate, install and initialize mkcert, then restart Drizzle Studio:

brew install mkcert
mkcert -install

pnpm db:studio

npm run db:studio

yarn db:studio

Drizzle’s official drizzle-kit studio docs also note that local certificate setup may be required for browsers that block or distrust the default localhost HTTPS flow: Drizzle Studio docs.

Code Quality

The project uses Husky hooks for local quality gates.

on git commit, Husky runs lint-staged
on git push, Husky runs the unit test script with a dot reporter

That means pushes to your remote can be blocked until the unit test suite passes.

If you want to know whether a push will pass before you actually push, run:

pnpm test -- --reporter=dot

npm run test -- --reporter=dot

yarn test --reporter=dot

Here --reporter=dot tells Vitest to use a compact dot-style output instead of a more verbose default report, which keeps push-time test logs shorter and easier to scan.

To run checks manually:

pnpm lint        # check for issues
pnpm lint:fix    # auto-fix
pnpm format      # format all files
pnpm typecheck   # TypeScript checks

npm run lint        # check for issues
npm run lint:fix    # auto-fix
npm run format      # format all files
npm run typecheck   # TypeScript checks

yarn lint        # check for issues
yarn lint:fix    # auto-fix
yarn format      # format all files
yarn typecheck   # TypeScript checks

Project Structure

├── app/                  # Nuxt frontend (pages, components, composables, layouts)
├── server/               # Backend (API routes, services, database, utils)
│   ├── api/              # Nitro route handlers
│   ├── services/         # Provider abstractions (Billing, Mailer, Storage, AI)
│   ├── database/schema/  # Drizzle ORM schema definitions
│   └── utils/            # Domain logic and helpers
├── shared/               # Shared code (validation schemas, config)
├── content/              # Nuxt Content markdown (in-app docs)
└── public/               # Static assets