Skip to main content

​
Prerequisites

Before you begin, ensure you have the following installed:

VS Code

Microsoft’s code editor

Dev Containers Extension

Run dev environments in containers

Docker

Container runtime
The Dev Container setup is the recommended way to get started. It automatically provisions Node.js (via Volta), Python (via pyenv), and PostgreSQL 18 in an isolated Ubuntu container.

​
Installation Steps

1

Clone the Repository

Clone the Auth UI Boilerplate repository to your local machine:
git clone https://github.com/your-org/auth-ui-boilerplate.git
cd auth-ui-boilerplate
Open the project in VS Code:
code .
2

Open in Dev Container

Once VS Code opens, you’ll see a notification to “Reopen in Container”.Alternatively, manually trigger it:
  • Press Cmd+Shift+P (Mac) or Ctrl+Shift+P (Windows/Linux)
  • Type “Dev Containers: Reopen in Container”
  • Select the command
The first build takes 2-5 minutes as Docker downloads the base image and sets up PostgreSQL 18, Node.js, Python, and Zsh with plugins.
The Dev Container configuration (.devcontainer/devcontainer.json) provides:
  • Ubuntu base with common utilities
  • Volta for Node.js version management
  • pyenv for Python version management
  • PostgreSQL 18 running on postgres:5432
  • Zsh with autosuggestions and syntax highlighting
3

Install Runtime Prerequisites

Once inside the container, install Node.js and Python:
volta install node
This installs the Node.js version specified in package.json (Node.js 22+).If you plan to use the Python backend examples, also install Python:
pyenv install 3.12
pyenv global 3.12
Verify installations:
node --version  # Should show v22.x.x or higher
npm --version   # Should show v10.x.x or higher
python --version # Should show Python 3.12.x
4

Configure Environment Variables

Copy the example environment file:
cp .env.example .env
The .env file contains the following configuration:
.env
# Database (pre-configured for Dev Container PostgreSQL)
DATABASE_URL=postgresql://postgres:postgres@postgres:5432/postgres

# Better Auth Secret (generate with: openssl rand -base64 32)
BETTER_AUTH_SECRET=change-me-to-a-random-secret

# Better Auth URLs
BETTER_AUTH_URL=http://localhost:3000
NEXT_PUBLIC_BETTER_AUTH_URL=http://localhost:3000

# Google OAuth (REQUIRED - see setup below)
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret

# Backend API (optional - only if you have an external backend)
# BACKEND_API_URL=http://localhost:8080
# NEXT_PUBLIC_BACKEND_API_URL=http://localhost:8080
You must update GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET to use Google OAuth. See the next section for setup instructions.

​
Generate Better Auth Secret

Generate a secure random secret for signing tokens:
openssl rand -base64 32
Replace BETTER_AUTH_SECRET in .env with the generated value.
5

Set Up Google OAuth

To enable Google sign-in, you need OAuth credentials from Google Cloud:
  1. Go to Google Cloud Console
  2. Create a new project (or select an existing one)
  3. Navigate to APIs & Services > Credentials
  4. Click Create Credentials > OAuth 2.0 Client ID
  5. Configure the OAuth consent screen if prompted
  6. Select Application type: Web application
  7. Add Authorized redirect URI: 
    http://localhost:3000/api/auth/callback/google
  8. Click Create and copy the Client ID and Client Secret
  9. Paste them into your .env file:
.env
GOOGLE_CLIENT_ID=123456789-abcdefg.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-your-secret-here
If you don’t want to use Google OAuth during development, you can skip this step and use email/password authentication instead. However, the Google sign-in button will not work.
6

Install Dependencies

Install all npm packages:
npm install
This installs:
  • Next.js 16 (React 19)
  • Better Auth (authentication library)
  • Drizzle ORM (database toolkit)
  • shadcn/ui components (Tailwind CSS)
  • Axios (HTTP client)
  • Motion (animations)
7

Push Database Schema

Create the required database tables in PostgreSQL:
npm run db:push
This command runs drizzle-kit push, which:
  • Reads the schema from src/db/schema.ts
  • Creates tables: user, session, account, verification, jwks
  • Does not generate migration files (for quick dev iteration)
db:push is recommended for development. For production, use npm run db:generate to create migration files, then npm run db:migrate to apply them.

​
Database Schema

The following tables are created automatically by Better Auth:
TableDescription
userUser accounts (id, name, email, image, timestamps)
sessionActive sessions with tokens and expiration
accountOAuth provider accounts (Google, GitHub, etc.)
verificationEmail verification tokens
jwksJSON Web Key Set for JWT signing/verification
8

Start the Development Server

Run the Next.js dev server:
npm run dev
The application will start on http://localhost:3000.You should see output similar to:
▲ Next.js 16.1.6
- Local:        http://localhost:3000
- Environments: .env

✓ Starting...
✓ Ready in 1.2s
9

Test Authentication

Open your browser and navigate to http://localhost:3000.

​
Sign Up with Email

  1. Click Sign Up in the navigation
  2. Enter your email and password
  3. Click Create Account
  4. You’ll be redirected to the home page, now authenticated

​
Sign In with Google

  1. Click Sign In in the navigation
  2. Click Sign in with Google
  3. Complete the Google OAuth flow
  4. You’ll be redirected back to the application

​
Verify Session

After signing in, you should see:
  • Your name and email displayed in the “Authentication Status” card
  • A Sign Out button
  • Access to protected features
The home page includes an API Test section for testing backend integration. This requires setting BACKEND_API_URL and running a backend service. See the Backend Integration guide for details.

​
What’s Next?

Environment Variables

Learn about all available configuration options

Database Management

Add custom tables and run migrations with Drizzle

Backend Integration

Connect Go, Python, or Express.js backends

Customize UI

Remove demo components and build your app

​
Troubleshooting

Solution: Ensure Docker is running and you have the Dev Containers extension installed. Check Docker Desktop for error logs.
# Rebuild the container from scratch
Cmd+Shift+P → "Dev Containers: Rebuild Container"
Solution: The Dev Container PostgreSQL service may not have started. Check the logs:
docker compose -f .devcontainer/docker-compose.yml logs postgres
Restart the container if needed.
Solution: Ensure your redirect URI in Google Cloud Console exactly matches:
http://localhost:3000/api/auth/callback/google
No trailing slashes, correct port, and http (not https) for local dev.
Solution: Make sure you copied .env.example to .env and generated a secret:
openssl rand -base64 32
Paste the result into BETTER_AUTH_SECRET in your .env file.

Build docs developers (and LLMs) love

Get started for freeTalk to us