Installation Prerequisites

You need Node.js 20.10+, pnpm, Docker (for Postgres and Mailpit), and Git. Docker handles the database and email testing service, so you don't need to install PostgreSQL separately.

This guide is part of the Next.js Drizzle SaaS Kit installation.

Node.js 20.10 or Later

The SaaS Kit requires Node.js version 20.10.0 or later. We recommend using the latest LTS version.

Check if Node.js is installed:

node --version

Install Node.js:

• Using Official Installer:
  • Download from nodejs.org
  • Choose the LTS (Long Term Support) version
  • Run the installer and follow the prompts

Bun may also work, but we cannot promise full compatibility.

• Alternative: Using nvm (Recommended for developers):
  # Install nvm (macOS/Linux)
  curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
  # Install latest LTS Node.js
  nvm install --lts
  nvm use --lts

To verify the installation, run the following commands:

node --version
npm --version

pnpm Package Manager

This project uses pnpm instead of npm or yarn for better performance and disk space efficiency.

Install pnpm globally:

npm install -g pnpm

Verify installation:

pnpm --version

Why pnpm?

• Faster - Up to 2x faster than npm
• Efficient - Saves disk space with content-addressable storage
• Strict - Better dependency management
• Monorepo support - Excellent for our Turborepo setup

PostgreSQL 16 or Later

You need a running PostgreSQL instance.

We recommend using the provided Docker compose file to run the database and the Mailer testing service.

If you have Docker up and running on your machine, you can run the following command to start the Postgres database and the Mailer testing service:

pnpm run compose:dev:up

This will spin up:

• Postgres: a PostgreSQL 17 instance on port 54333
• Mailpit: a service for testing emails locally (Web UI on port 8025, SMTP on port 1025)

Docker vs Hosted Database

Use Docker (recommended) when:

• Local development on your machine
• Testing migrations before deploying
• You want identical dev/prod database behavior
• Running E2E tests that need a fresh database

Use a hosted database when:

• Your team needs shared development data
• Docker has issues on your machine (M1 Mac, corporate restrictions)
• You're already using Neon, Supabase, or Railway for production

If unsure: Start with Docker for the smoothest local experience. You can switch to a hosted database later by updating DATABASE_URL in .env.local.

Git

Required for cloning the repository and version control.

Check if Git is installed:

git --version

Docker Desktop/Orbstack

Useful for running PostgreSQL and other services in containers.

Download:

• macOS/Windows: docker.com/products/docker-desktop
• Linux: Follow Docker Engine installation

On MacOS, we recommend using Orbstack instead of Docker Desktop. It is a lighter alternative that is faster and more efficient.

Download:

• macOS: orbstack.dev

Database Management Tools

To inspect and manage your database:

Drizzle Studio (Recommended - Built-in):

# Run after installation is complete
pnpm --filter "@kit/database" drizzle:studio

Drizzle Studio provides a browser-based interface to view and edit your database tables directly. It launches at https://local.drizzle.studio after running the command.

Email Service

All emails will be logged to the console for local development. However, we recommend setting up an email testing service to test email features (invitations, password reset).

This is also required for full end-to-end testing of the kit - since it relies on emails being sent and received.

We recommend using Mailpit to test emails locally. This will be run automatically when you start the provided Docker compose file.

Common Pitfalls

• Node version manager conflicts - If using nvm, fnm, or volta, ensure the correct version is active in your terminal before running commands
• pnpm installed but wrong version - The kit requires pnpm 9.x or 10.x; older versions may fail silently on workspace features
• Docker not running in background - Docker Desktop/Orbstack must be running before pnpm run compose:dev:up will work
• Firewall blocking Docker ports - Ensure ports 54333 (Postgres), 8025 (Mailpit UI), and 1025 (Mailpit SMTP) are not blocked by your firewall or another service
• Apple Silicon Rosetta issues - On M1/M2 Macs, ensure Docker is configured for ARM64, not running under Rosetta emulation

Verification Checklist

Before proceeding, verify you have:

• [ ] Node.js 20.10 or later installed
• [ ] pnpm installed globally
• [ ] Docker Desktop or Orbstack running
• [ ] Git installed and configured

Next: Clone Repository →