Installation Guide

This guide provides comprehensive instructions for installing and configuring your ORPC + Better Auth application. Whether you’re setting up for local development or preparing for production, this guide covers everything you need.

System Requirements

Node.js: Version 20.0.0 or higher
Package Manager: pnpm 9.15.4+ (recommended), npm, or yarn
Operating System: macOS, Windows, or Linux
Memory: At least 4GB RAM recommended
Disk Space: ~500MB for dependencies

Package Manager Setup

This project uses pnpm as the package manager. While you can use npm or yarn, pnpm is recommended for its speed and efficiency.

Installing pnpm

npm install -g pnpm

Verify the installation:

pnpm --version
# Should output: 9.15.4 or higher

Project Setup

Clone the Repository

Clone the starter template to your local machine:

git clone <repository-url> my-app
cd my-app

Replace <repository-url> with the actual repository URL and my-app with your project name.

Install Dependencies

Install all required packages:

pnpm install

This installs all dependencies defined in package.json:Core Dependencies:

@orpc/[email protected] - ORPC server-side runtime
@orpc/[email protected] - ORPC client for making type-safe calls
@orpc/[email protected] - TanStack Query integration
[email protected] - Authentication library
[email protected] - Next.js framework
[email protected] - React library
[email protected] - TypeScript ORM
@libsql/[email protected] - SQLite/Turso client
[email protected] - Schema validation

UI Dependencies:

[email protected] - Primitive UI components
[email protected] - Tailwind utility function
[email protected] - CSS variant management
[email protected] - Icon library
[email protected] - Theme management
[email protected] - Toast notifications

Development Tools:

@biomejs/[email protected] - Fast linter and formatter
[email protected] - Drizzle ORM CLI tools
typescript@5 - TypeScript compiler

Environment Configuration

Create your environment configuration file:

cp .env.example .env

The .env.example file contains:

.env.example

NEXT_PUBLIC_SERVER_URL=http://localhost:3000
DATABASE_URL=file:./local.db

Environment Variables Explained

NEXT_PUBLIC_SERVER_URL

string

required

The base URL for your application. Used by:

ORPC client for API calls (/rpc endpoint)
Better Auth client for authentication requests

Local development: http://localhost:3000Production: Your deployed URL (e.g., https://myapp.com)

Must include the protocol (http:// or https://) and match the URL you’re accessing. CORS and authentication cookies depend on this being correct.

DATABASE_URL

string

required

Database connection string for Drizzle ORM.Local SQLite: file:./local.dbTurso (production): libsql://[database-name].turso.io?authToken=[token]The Turso CLI (pnpm db:local) uses this to create a local database file.

BETTER_AUTH_SECRET

string

Secret key for encrypting sessions and tokens. Required for production.Generate a secure random string:

openssl rand -base64 32

Keep this secret and never commit it to version control. Use different values for development and production.

BETTER_AUTH_URL

string

The base URL for Better Auth. Defaults to NEXT_PUBLIC_SERVER_URL if not set.Only needed if your auth endpoint is on a different domain.

CORS_ORIGIN

string

Allowed origin for CORS requests. Used by Better Auth to validate request origins.Development: Usually not needed (defaults to NEXT_PUBLIC_SERVER_URL)Production: Set to your frontend domain if different from API

Database Configuration

This project uses Drizzle ORM with SQLite/Turso for the database. Two options are available:

Option 1: Local SQLite (Development)

Best for local development and testing.

Start the Local Database

The Turso CLI provides a local SQLite server:

pnpm db:local

This command:

Creates a local.db file in your project root
Starts a Turso-compatible local server
Watches for schema changes

Keep this terminal running while you develop. The database server needs to be active for your application to work.

Push the Schema

Apply your database schema to create the tables:

pnpm db:push

This creates tables for:

Authentication: user, session, account, verification
Application: todo (example table)

The schema is defined in:

src/db/schema/auth.ts - Better Auth tables
src/db/schema/todo.ts - Application tables

Verify the Setup

Open Drizzle Studio to inspect your database:

pnpm db:studio

This opens a web interface at https://local.drizzle.studio where you can:

Browse tables and data
Run queries
Inspect schema structure

Option 2: Turso (Production)

Recommended for production deployments.

Install Turso CLI

curl -sSfL https://get.tur.so/install.sh | bash

Or use your package manager:

brew install tursodatabase/tap/turso

Create a Turso Database

turso auth signup
turso db create my-app-db

Get Connection Credentials

Retrieve your database URL and authentication token:

turso db show my-app-db --url
turso db tokens create my-app-db

Update your .env file:

DATABASE_URL=libsql://my-app-db.turso.io?authToken=your-token-here

Push Schema to Turso

Apply your schema to the production database:

pnpm db:push

Drizzle Configuration

The database configuration is in drizzle.config.ts:

drizzle.config.ts

import { defineConfig } from "drizzle-kit"

export default defineConfig({
  schema: "./src/db/schema",
  out: "./src/db/migrations",
  dialect: "turso",
  dbCredentials: {
    url: process.env.DATABASE_URL || ""
  }
})

Database Schema Files

Authentication Schema (src/db/schema/auth.ts): Better Auth automatically creates these tables via Drizzle adapter:

user - User accounts
session - Active sessions
account - OAuth accounts (if enabled)
verification - Email verification tokens

Application Schema (src/db/schema/todo.ts):

import { integer, sqliteTable, text } from "drizzle-orm/sqlite-core"

export const todo = sqliteTable("todo", {
  id: integer("id").primaryKey({ autoIncrement: true }),
  text: text("text").notNull(),
  completed: integer("completed", { mode: "boolean" }).default(false).notNull()
})

Verification Steps

Before starting development, verify your installation:

Check TypeScript

Run the type checker:

pnpm typecheck

You should see no errors. If you do, make sure all dependencies are installed correctly.

Verify Database Connection

Test the database connection by starting the dev server and checking for errors:

pnpm dev

Look for successful startup messages. No database connection errors should appear.

Test ORPC Health Check

Visit the health check endpoint:

curl http://localhost:3000/rpc/healthCheck

You should see: "OK"

Verify Better Auth

Check that the auth endpoint is responding:

curl http://localhost:3000/api/auth/session

You should see a JSON response (likely null for no session, which is expected).

Available Scripts

Your package.json includes these helpful scripts:

{
  "scripts": {
    "dev": "next dev --turbopack --port 3000",
    "build": "next build",
    "start": "next start",
    "lint": "biome check && pnpm run typecheck",
    "format": "biome format --write .",
    "typecheck": "tsc --noEmit",
    "db:local": "turso dev --db-file local.db",
    "db:push": "drizzle-kit push",
    "db:studio": "drizzle-kit studio",
    "db:generate": "drizzle-kit generate",
    "db:migrate": "drizzle-kit migrate"
  }
}

Script Descriptions

dev

command

Start the development server with Turbopack on port 3000Hot reload: Automatically reloads on file changesType updates: ORPC types update instantly when you change procedures

build

command

Create an optimized production buildRun this before deploying to verify there are no build errors

start

command

Start the production server (after building)Use this to test the production build locally

lint

command

Run Biome linter and TypeScript type checkerChecks for code quality issues and type errors

format

command

Format code with BiomeAutomatically fixes formatting issues

db:local

command

Start local SQLite database serverKeep this running in a separate terminal during development

db:push

command

Push schema changes to databaseUse this to apply schema changes without creating migration files

db:studio

command

Open Drizzle StudioVisual database browser and query tool

db:generate

command

Generate migration filesCreates SQL migration files from schema changes

db:migrate

command

Run migrationsApplies migration files to the database

Troubleshooting

pnpm install fails

Solution 1: Clear pnpm cache

pnpm store prune
pnpm install

Solution 2: Delete lock file and node_modules

rm -rf node_modules pnpm-lock.yaml
pnpm install

Solution 3: Check Node.js version

node --version  # Should be 20.0.0 or higher

Database connection errors

Make sure:

The db:local command is running
DATABASE_URL in .env is correct
You have write permissions in the project directory
No other process is using the database file

Try recreating the database:

rm local.db
pnpm db:local
# In another terminal:
pnpm db:push

Type errors in editor

Restart your TypeScript server (VS Code: Cmd+Shift+P → “TypeScript: Restart TS Server”)
Make sure src/routers/index.ts exports AppRouter type
Check that ORPC client imports match your router structure
Run pnpm typecheck to see all type errors

Port already in use

Change the port in package.json:

"dev": "next dev --turbopack --port 3001"

Update .env:

NEXT_PUBLIC_SERVER_URL=http://localhost:3001

Biome formatting conflicts with other formatters

Disable other formatters (Prettier, ESLint) in your editor settings.For VS Code, add to .vscode/settings.json:

{
  "editor.defaultFormatter": "biomejs.biome",
  "editor.formatOnSave": true
}

Next Steps

Your installation is complete! Here’s what to do next:

Quickstart

Follow the quickstart guide to build your first feature

Core Concepts

Learn how ORPC and Better Auth work

Database Setup

Set up your database with Drizzle and Turso

API Reference

Explore available procedures and types

Get Started

Core Concepts

Guides

Installation

Installation Guide

System Requirements

Package Manager Setup

Installing pnpm

Project Setup

Environment Variables Explained

Database Configuration

Option 1: Local SQLite (Development)

Option 2: Turso (Production)

Drizzle Configuration

Database Schema Files

Verification Steps

Available Scripts

Script Descriptions

Troubleshooting

Next Steps

Quickstart

Core Concepts

Database Setup

API Reference

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

​Installation Guide

​System Requirements

​Package Manager Setup

​Installing pnpm

​Project Setup

​Environment Variables Explained

​Database Configuration

​Option 1: Local SQLite (Development)

​Option 2: Turso (Production)

​Drizzle Configuration

​Database Schema Files

​Verification Steps

​Available Scripts

​Script Descriptions

​Troubleshooting

​Next Steps

Quickstart

Core Concepts

Database Setup

API Reference

Build docs developers (and LLMs) love

Installation Guide

System Requirements

Package Manager Setup

Installing pnpm

Project Setup

Environment Variables Explained

Database Configuration

Option 1: Local SQLite (Development)

Option 2: Turso (Production)

Drizzle Configuration

Database Schema Files

Verification Steps

Available Scripts

Script Descriptions

Troubleshooting

Next Steps