Quickstart

Prerequisites

Before you begin, make sure you have:

Node.js 20+ (download)
Bun (install with curl -fsSL https://bun.sh/install | bash)
A GitHub account (for cloning and OAuth)

Understanding `bun chatjs:init`

The bun chatjs:init command generates a chat.config.ts file with sensible defaults. This file controls all feature toggles, branding, and app settings.

What the default config includes

The default configuration gives you a minimal, working setup:

Setting	Default	Notes
Authentication	GitHub only	Google and Vercel OAuth disabled
Integrations	All disabled	No sandbox, web search, MCP, image generation, or attachments
Anonymous users	10 credits	Limited access, no tools
Models	Curated list	GPT-5 Nano/Mini, Gemini 2.5 Flash Lite, Claude Sonnet 4.5

This keeps your initial setup simple—you only need DATABASE_URL, AUTH_SECRET, AI_GATEWAY_API_KEY, and GitHub OAuth credentials to get started.Enable features incrementally by editing chat.config.ts and adding the required environment variables. See Configuration for details.

Vercel (Recommended)
Manual Setup

The fastest path to production. Vercel handles database, blob storage, and AI Gateway automatically.

1. Deploy to Vercel

This creates a new repo in your GitHub account and deploys it to Vercel. During setup, Vercel provisions:

PostgreSQL database
Blob storage
AI Gateway access (120+ models)

2. Configure Authentication

In the Vercel dashboard, go to Settings → Environment Variables and add:

Variable	Description
`AUTH_SECRET`	Generate one

Then add credentials for at least one OAuth provider:

GitHub (Recommended)

Go to GitHub Developer Settings
Click New OAuth App
Set Homepage URL to your Vercel deployment URL
Set Authorization callback URL to https://YOUR_APP.vercel.app/api/auth/callback/github
Copy the Client ID → AUTH_GITHUB_ID
Generate a Client Secret → AUTH_GITHUB_SECRET

Google

Go to Google Cloud Console
Create a new OAuth 2.0 Client ID (Web application)
Add Authorized redirect URI: https://YOUR_APP.vercel.app/api/auth/callback/google
Copy Client ID → AUTH_GOOGLE_ID
Copy Client Secret → AUTH_GOOGLE_SECRET

Vercel

Go to Vercel Integration Console
Create a new integration with Sign In with Vercel
Copy Client ID → VERCEL_APP_CLIENT_ID
Copy Client Secret → VERCEL_APP_CLIENT_SECRET

3. Set Up Local Development

Clone your new repo and pull environment variables from Vercel:

git clone https://github.com/YOUR_USERNAME/YOUR_REPO.git
cd YOUR_REPO
bun install
bun chatjs:init  # Generate chat.config.ts with minimal defaults (can re-run to reset)
vercel link
vercel env pull .env.local

4. Run Database Migrations

bun db:migrate

5. Start the Dev Server

bun dev

Open http://localhost:3000. You should see the ChatJS interface with a model selector and chat input.

For self-hosted deployments or when you want full control over infrastructure.

1. Create Your Project

Click “Use this template” on the ChatJS repo, then clone:

git clone https://github.com/YOUR_USERNAME/YOUR_REPO.git
cd YOUR_REPO
bun install
bun chatjs:init  # Generate chat.config.ts with minimal defaults (can re-run to reset)

2. Set Up External Services

You need a PostgreSQL database and blob storage. Here are the recommended options:

Database (PostgreSQL)

Option A: Vercel Postgres (easiest)

Go to Vercel Storage
Create a new Postgres database
Copy the connection string → DATABASE_URL

Option B: Neon (generous free tier)

Go to Neon
Create a project and database
Copy the connection string → DATABASE_URL

Option C: Local PostgreSQL

# macOS
brew install postgresql && brew services start postgresql
createdb chatjs
# DATABASE_URL=postgres://localhost:5432/chatjs

Blob Storage (Optional)

Required for file attachments and image generation. Skip if you don’t need these features.

Go to Vercel Blob
Create a new blob store
Copy the token → BLOB_READ_WRITE_TOKEN

To disable, set integrations.attachments: false and integrations.imageGeneration: false in chat.config.ts.

AI Gateway

ChatJS uses Vercel AI Gateway to access 120+ models through a single API.

Go to Vercel AI Gateway
Create an API key
Copy the key → AI_GATEWAY_API_KEY

See Multi-Model Support for details on model configuration.

3. Configure Environment Variables

cp .env.example .env.local

Fill in the required variables:

Variable	Description
`DATABASE_URL`	PostgreSQL connection string
`AUTH_SECRET`	Generate one
`AI_GATEWAY_API_KEY`	From Vercel AI Gateway
`APP_URL`	Your app’s public URL (e.g., `https://myapp.com`)

4. Configure Authentication

Add credentials for at least one OAuth provider:

GitHub (Recommended)

Go to GitHub Developer Settings
Click New OAuth App
Set Homepage URL to http://localhost:3000
Set Authorization callback URL to http://localhost:3000/api/auth/callback/github
Copy the Client ID → AUTH_GITHUB_ID
Generate a Client Secret → AUTH_GITHUB_SECRET

Google

Go to Google Cloud Console
Create a new OAuth 2.0 Client ID (Web application)
Add Authorized redirect URI: http://localhost:3000/api/auth/callback/google
Copy Client ID → AUTH_GOOGLE_ID
Copy Client Secret → AUTH_GOOGLE_SECRET

Vercel

Go to Vercel Integration Console
Create a new integration with Sign In with Vercel
Copy Client ID → VERCEL_APP_CLIENT_ID
Copy Client Secret → VERCEL_APP_CLIENT_SECRET

5. Run Database Migrations

bun db:migrate

6. Start the Dev Server

bun dev

Open http://localhost:3000. You should see the ChatJS interface with a model selector and chat input.

Troubleshooting

Missing environment variables error

ChatJS validates env vars at build time. Check .env.local has all required variables and restart the dev server.

Database connection failed

Verify DATABASE_URL is correct and the database is running. For local PostgreSQL, check the service is started.

OAuth redirect error

Make sure the callback URL in your OAuth app matches exactly. For local dev, use http://localhost:3000/api/auth/callback/{provider}.

Optional Features

These environment variables enable additional capabilities:

Variable	Feature	Setup Guide
`REDIS_URL`	Resumable streams	Vercel KV
`TAVILY_API_KEY`	Web search	Tavily
`FIRECRAWL_API_KEY`	Web search	Firecrawl
`LANGFUSE_PUBLIC_KEY`	LLM observability	Langfuse
`LANGFUSE_SECRET_KEY`	LLM observability	Langfuse
`MCP_ENCRYPTION_KEY`	MCP connectors	`openssl rand -base64 32` (must be exactly 44 chars)
`CRON_SECRET`	Cleanup cron job	Generate

Next Steps

You’re up and running. Here’s where to go next:

Configuration

Customize features, branding, and integrations in chat.config.ts

AI Capabilities

Explore built-in tools: web search, image generation, code execution

Getting Started

Core Concepts

Features

Customization

Deployment

Reference

Roadmap

Prerequisites

Understanding `bun chatjs:init`

1. Deploy to Vercel

2. Configure Authentication

3. Set Up Local Development

4. Run Database Migrations

5. Start the Dev Server

1. Create Your Project

2. Set Up External Services

3. Configure Environment Variables

4. Configure Authentication

5. Run Database Migrations

6. Start the Dev Server

Troubleshooting

Next Steps

Configuration

AI Capabilities

Getting Started

Core Concepts

Features

Customization

Deployment

Reference

Roadmap

​Prerequisites

​Understanding bun chatjs:init

​1. Deploy to Vercel

​2. Configure Authentication

​3. Set Up Local Development

​4. Run Database Migrations

​5. Start the Dev Server

​1. Create Your Project

​2. Set Up External Services

​3. Configure Environment Variables

​4. Configure Authentication

​5. Run Database Migrations

​6. Start the Dev Server

​Troubleshooting

​Next Steps

Configuration

AI Capabilities

Prerequisites

Understanding `bun chatjs:init`

1. Deploy to Vercel

2. Configure Authentication

3. Set Up Local Development

4. Run Database Migrations

5. Start the Dev Server

1. Create Your Project

2. Set Up External Services

3. Configure Environment Variables

4. Configure Authentication

5. Run Database Migrations

6. Start the Dev Server

Troubleshooting

Next Steps