Running Locally
Start Docker services, migrate the database, and launch the Next.js dev server.
Congratulations on setting up your environment variables! Now it's time to bring your SaaS Boilerplate application to life on your local machine. This guide will walk you through starting the necessary services, preparing your database, and launching the development server. We'll explain each step so you understand what's happening behind the scenes, and provide tips for troubleshooting common issues. By the end, you'll have a fully functional app running at http://localhost:3000, ready for development and testing.
Prerequisites
Before diving in, ensure you've completed the Environment Setup guide. You'll need:
- A properly configured
.envfile with at least the core variables (likeDATABASE_URLandBETTER_AUTH_SECRET). - Docker Desktop installed and running, as we'll use it for the database.
- Node.js and your package manager (npm, pnpm, or yarn) ready.
If you haven't done this yet, go back and follow the environment setup—it's essential for everything to work smoothly.
Why These Steps Matter
Running a modern web app like the SaaS Boilerplate involves multiple moving parts: a database for data storage, background services for tasks, and the app itself. We'll start the database first (using Docker), then prepare it with your schema, and finally launch the app. This ensures everything is connected and ready. Think of it like starting a car: fuel (database), engine check (migrations), and ignition (dev server).
Starting Your Local Environment
Follow these steps in order. Each one builds on the previous, and we'll explain what each command does and why it's necessary.
Start Dependencies with Docker
The first step is to launch your local database and any other services. The boilerplate uses Docker Compose to manage this easily.
Run this command in your terminal:
npm run docker:upWhat this does: This script starts PostgreSQL (your database) and possibly Redis (for caching/jobs) in Docker containers. Docker Compose reads docker-compose.yml to know what to run.
Why it's needed: Your app needs a database to store users, sessions, and app data. Running it in Docker means you don't have to install PostgreSQL directly on your machine, keeping things clean and isolated.
What to expect: You'll see output like "Starting postgres... done." It might take a minute the first time as Docker downloads images. Once complete, PostgreSQL will be running on localhost:5432.
Troubleshooting tip: If it fails, ensure Docker Desktop is open and running. Check docker ps to see if containers started. If ports conflict, edit docker-compose.yml to use different ports.
Apply Database Migrations
With the database running, you need to set up its structure—creating tables for users, sessions, etc.
Run:
npm run db:migrate:devWhat this does: This uses Prisma (the database toolkit) to run migration files. Migrations are like blueprints that define your database schema.
Why it's needed: Without tables, your app can't save data. This step creates the necessary structure based on prisma/schema.prisma.
What to expect: Output like "Applying migration..." and success messages. If it's your first time, it might create initial data.
Troubleshooting tip: If it says "connection refused," double-check DATABASE_URL in .env and ensure Docker is running. Run npm run db:studio to inspect the database manually.
Start the Development Server
Now, launch the Next.js app itself.
Run:
npm run devWhat this does: This starts the Next.js development server, which compiles your code, serves it at http://localhost:3000, and enables hot reloading (changes update automatically).
Why it's needed: This is your app! Without it, you can't access the frontend or API.
What to expect: Messages like "Ready - started server on 0.0.0.0:3000" and "Compiled successfully." Open http://localhost:3000 in your browser to see the app.
Troubleshooting tip: If port 3000 is busy, Next.js will suggest an alternative. Check for errors in the console—missing env vars often cause issues.
Optional: Inspect the Database
To see what's in your database, open Prisma Studio.
Run:
npm run db:studioWhat this does: Launches a web interface at http://localhost:5555 for browsing and editing database data.
Why it's useful: Great for debugging—see users, sessions, etc. Without affecting production.
What to expect: A browser window opens with your tables. You can view/edit data safely.
Optional: Set Up Billing Webhooks
If testing payments, start a local webhook listener for Stripe.
Run:
npm run stripe:webhookWhat this does: Uses the Stripe CLI to forward webhooks from Stripe to your local app.
Why it's useful: Stripe sends events (like "payment succeeded") via webhooks. This lets you test them locally.
What to expect: A tunnel URL and webhook secret. Update STRIPE_WEBHOOK_SECRET in .env if needed.
Troubleshooting tip: Requires Stripe CLI installed. Ensure your app's webhook endpoint is set up.
Verifying Your Setup
Once everything is running, verify it works:
- App loads: Visit
http://localhost:3000—you should see the homepage. - Docs accessible: Go to
http://localhost:3000/docsfor built-in documentation. - Database connected: Try signing up a user or checking Prisma Studio.
- API responds: Test an endpoint, like
/api/health, if available.
If anything fails, check the troubleshooting section below.
Troubleshooting
Running locally can sometimes hit snags. Here's how to resolve the most frequent problems:
For more help, check the Next.js local development docs or Docker troubleshooting.
Next Steps
Develop Features
Edit code and see changes instantly with hot reload.
Test Integrations
Try auth, billing, file uploads, and more.
Debug
Use browser dev tools and console logs.
Deploy
When ready, follow the First Deploy guide.
If you stop development, shut down with Ctrl+C in terminals and npm run docker:down to clean up.
See Also
- Environment Setup - Configure your
.envfile. - Quickstart - Overview of getting started.
- First Deploy - Move to production.
- Architecture Overview - Understand the codebase.
- Testing - How to test your changes.