Installation

Prerequisites

Before you begin, ensure you have the following installed:

• Node.js: Version 20.10 or higher (LTS recommended)
• npm or pnpm: Package manager
• PostgreSQL: Local or remote instance for the database

VS Code Extensions

Recommended extensions for the best development experience:

[!TIP] When adding new translation keys, run "TypeScript: Restart TS Server" (Cmd/Ctrl+Shift+P) for i18n Ally to recognize them.

Step 1: Clone the Repository

git clone <repository-url>
cd next-template

Step 2: Install Dependencies

Using npm:

npm install

Or using pnpm:

pnpm install

Step 3: Environment Setup

Copy the example environment file:

cp .env.local.example .env

Required Environment Variables

Open .env and fill in these required values:

Database

DATABASE_URL="postgresql://user:password@localhost:5432/mydb"

Authentication

Generate a secret key (minimum 32 characters):

BETTER_AUTH_SECRET="your-secret-key-min-32-chars"
BETTER_AUTH_URL="http://localhost:3000"

Optional Services

Configure these if you plan to use them:

# Email (Resend)
RESEND_API_KEY=""

# File Storage (S3/R2)
S3_ACCESS_KEY=""
S3_SECRET_KEY=""
S3_BUCKET=""
S3_REGION=""
S3_ENDPOINT=""

# OAuth Providers
GOOGLE_CLIENT_ID=""
GOOGLE_CLIENT_SECRET=""
GITHUB_CLIENT_ID=""
GITHUB_CLIENT_SECRET=""

See src/env/env-server.ts for the complete list of environment variables.

Step 4: Database Setup

Initialize RLS Roles

First, set up the required PostgreSQL roles and functions for Row Level Security:

npm run db:setup

[!IMPORTANT] This is required only once per database. It creates the roles (authenticated, anonymous, admin, service) and the auth.user_id() function used by RLS policies.

Push Schema

Push the schema to your database:

npm run db:push

This command uses Drizzle Kit to synchronize your database schema with the table definitions in src/db/tables/.

What This Does

• Creates all tables defined in src/db/tables/
• Sets up primary keys, foreign keys, and indexes
• Applies default values and constraints
• Enables Row Level Security (RLS) policies

Database Tables

The schema includes tables for:

• Authentication - user, session, account, verification
• Organizations - organization, organization_member, organization_invitation
• API Keys - api_key
• Settings - user_settings

See src/db/tables/ for complete table definitions.

Step 5: Run the Development Server

Start the development server:

npm run dev

Open http://localhost:3000 in your browser. You should see the homepage.

Local Admin Shortcut

If you need admin access in local development, sign in with the target user, then open:

http://localhost:3000/api/grant-admin

Troubleshooting

Database Connection Fails

• Verify PostgreSQL is running
• Check DATABASE_URL format
• Ensure database exists and user has permissions

Role "authenticated" Does Not Exist

If db:push fails with this error:

role "authenticated" does not exist

You need to run the database setup first:

npm run db:setup

See Database Setup for details.

Port Already in Use

Change the port in package.json:

{
  "scripts": {
    "dev": "next dev -p 3001"
  }
}

Missing Environment Variables

Check for typos in .env and ensure all required variables are set. The app will throw validation errors for missing required vars on startup.

Next Steps

• Quick Start - Run the app and create your first feature
• Project Structure - Understand folder organization