Demo
General
Codebase

Local Development

Learn how to set up your local development environment.

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:

Setting Up Local Services

Option 1: Local PostgreSQL Installation

Install PostgreSQL on your machine and create a database:

Terminal
createdb your_database_name

Option 2: Docker Compose (Recommended)

Create a docker-compose.yml file in your project root with the following configuration:

docker-compose.yml
version: '3.8'

services:
  postgres:
    image: postgres:15-alpine
    container_name: pro-nextjs-postgres
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: pro_nextjs
    ports:
      - '5432:5432'
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U postgres']
      interval: 5s
      timeout: 5s
      retries: 5

volumes:
  postgres_data:

Starting the Services

  1. Start the services using Docker Compose:
Terminal
docker-compose up -d
  1. Verify that the services are running:
Terminal
docker-compose ps

Environment Configuration

Create or update your .env file with the following configuration:

.env
# Database
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/pro_nextjs"

# Authentication (required)
BETTER_AUTH_SECRET="your-secret-key-here"

# Stripe (optional, for billing features)
STRIPE_SECRET_KEY="sk_test_..."
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY="pk_test_..."
STRIPE_WEBHOOK_SECRET="whsec_..."

# Email (optional, for email features)
RESEND_API_KEY="re_..."
EMAIL_FROM="noreply@example.com"

Accessing the Services

  • PostgreSQL:
    • Host: localhost
    • Port: 5432
    • Username: postgres
    • Password: postgres
    • Database: pro_nextjs

Running Database Migrations

After setting up your database, run the migrations:

Terminal
npm run db:migrate:dev

This command will:

  • Create and apply migrations
  • Automatically regenerate Prisma Client

Start Development Server

Start the development server:

Terminal
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:
Terminal
docker-compose ps postgres
  1. Check the logs:
Terminal
docker-compose logs postgres
  1. 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:

Terminal
PORT=3001 npm run dev

Stopping the Services

To stop all services:

Terminal
docker-compose down

To stop and remove all data (including volumes):

Terminal
docker-compose down -v

Additional Resources