Local Development Setup

Get Better Hub running on your local machine

This guide walks you through setting up Better Hub for local development.

Prerequisites

Before you begin, ensure you have the following installed:

• Node.js 22 or higher
• pnpm 10 or higher (package manager)
• Docker (for running PostgreSQL locally)
• Git (for version control)

You’ll also need:

• A GitHub account
• A GitHub OAuth App (create one here)

When creating your GitHub OAuth App, set the callback URL to http://localhost:3000/api/auth/callback/github for local development.

Setup Steps

1. Clone the repository

   Clone the Better Hub repository to your local machine:

   git clone https://github.com/better-auth/better-hub.git
   cd better-hub
   
2. Use the correct Node.js version

   The project includes an .nvmrc file specifying Node.js 22. If you use nvm, run:

   nvm use
   

   This ensures you’re using the correct Node.js version for the project.

3. Start PostgreSQL with Docker

   Better Hub uses PostgreSQL for data storage. Start it using Docker Compose:

   docker compose up -d
   

   This runs PostgreSQL in the background. The database configuration is in docker-compose.yml.

4. Configure environment variables

   Copy the example environment file and fill in the required values:

   cp apps/web/.env.example apps/web/.env
   

   Open apps/web/.env and configure the following variables:

   Required Environment Variables

   • DATABASE_URL - PostgreSQL connection string (provided by Docker Compose)
   • GITHUB_CLIENT_ID - From your GitHub OAuth App
   • GITHUB_CLIENT_SECRET - From your GitHub OAuth App
   • BETTER_AUTH_SECRET - Generate a random string for session encryption
   • BETTER_AUTH_URL - Set to http://localhost:3000 for local development

   Optional but recommended for full functionality:

   • AI provider keys (OpenRouter, Anthropic, etc.)
   • Redis connection (Upstash)
   • S3/R2 for file uploads
5. Install dependencies

   Install all project dependencies using pnpm:

   pnpm install
   

   This installs dependencies for all workspaces in the monorepo.

6. Run database migrations

   Set up the database schema using Prisma:

   cd apps/web && npx prisma migrate dev && cd ../..
   

   This creates all necessary database tables based on the Prisma schema.

7. Start the development server

   Launch the development server:

   pnpm dev
   

   The application will be available at http://localhost:3000.

Development Scripts

Run these commands from the monorepo root:

Development

pnpm dev          # Start all apps in development mode

Always run pnpm check before pushing changes to ensure your code passes all quality checks.

Troubleshooting

Port 3000 already in use

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

PORT=3001 pnpm dev

Database connection errors

Ensure Docker is running and PostgreSQL is up:

docker compose ps

If the database isn’t running, restart it:

docker compose down
docker compose up -d

Prisma client out of sync

If you see Prisma-related errors, regenerate the Prisma client:

cd apps/web && npx prisma generate && cd ../..

GitHub OAuth not working

Verify your GitHub OAuth App settings:

• Homepage URL: http://localhost:3000
• Authorization callback URL: http://localhost:3000/api/auth/callback/github
• Client ID and Secret match your .env file

Next Steps

Now that you have Better Hub running locally:

• Read the Contributing Guidelines to understand the PR workflow
• Explore the Architecture Overview to understand the codebase structure
• Start building features or fixing bugs!