Local Development

This guide will help you set up your local development environment for the Pro Next.js Prisma starter kit, including the necessary services like PostgreSQL.

Prerequisites

To run the application locally, you need to have the following:

• Node.js 22.21.1, matching the version in package.json
• npm (comes with Node.js)
• PostgreSQL (v14 or later)

Recommended Startup Order

Start only the services needed for the flow you are testing:

The Stripe command requires the Stripe CLI and an authenticated Stripe account. Copy the temporary whsec_... value it prints into STRIPE_WEBHOOK_SECRET, then restart Next.js.

Setting Up Local Services

Option 1: Local PostgreSQL Installation

Install PostgreSQL on your machine and create a database:

createdb your_database_name

Option 2: Docker Compose (Recommended)

The repository includes a docker-compose.yml file with PostgreSQL 17. It creates a database named database with the password password.

Starting the Services

1. Start the services using Docker Compose:

npm run docker:up

2. Verify that the services are running:

docker compose ps

Environment Configuration

Start from the environment template shipped with the repository:

cp .env.example .env

The template already contains the local Docker database URL and NEXT_PUBLIC_SITE_URL. Replace its example BETTER_AUTH_SECRET with a unique value before starting the application:

Optional integrations may remain empty until you test them. Password signup does require RESEND_API_KEY and EMAIL_FROM because new accounts must verify their email. Use the environment variables guide to select complete variable groups for email, Stripe, Google sign-in, AI, storage, Turnstile and Sentry.

Accessing the Services

• PostgreSQL:
  • Host: localhost
  • Port: 5432
  • Username: postgres
  • Password: password
  • Database: database

Running Database Migrations

After setting up your database, run the migrations:

npm run db:migrate:dev

This command will:

• Create and apply migrations
• Automatically regenerate Prisma Client

Start Development Server

Start the development server:

npm run dev

Your application should now be running at http://localhost:3000 with the local PostgreSQL database.

Troubleshooting

Database Connection Issues

If you're having trouble connecting to PostgreSQL:

1. Verify the database is running:

docker compose ps postgres

2. Check the logs:

docker compose logs postgres

3. Verify your DATABASE_URL in .env matches your database configuration

Port Already in Use

If port 3000 is already in use, you can change it by setting the PORT environment variable:

PORT=3002 npm run dev

Port 3001 is reserved by the included React Email preview command. If you change the application port, also update NEXT_PUBLIC_SITE_URL, OAuth callback URLs and the target used by Stripe webhook forwarding.

Stopping the Services

To stop all services:

npm run docker:down

To stop and remove all data (including volumes):

docker compose down -v

Additional Resources

• Docker Compose Documentation
• PostgreSQL Documentation
• Next.js Documentation
• Prisma Documentation