Quickstart

Get ChatJS running in minutes

Prerequisites

Before you begin, make sure you have:

• Node.js 20+ (download)
• A package manager: npm, yarn, pnpm, or bun

1. Create Your Project

Scaffold a new ChatJS app using the CLI:

npx @chat-js/cli@latest create my-app
cd my-app

The CLI walks you through selecting your AI gateway, features, and auth providers, then generates a configured project with chat.config.ts ready to go. It also asks whether to include an Electron desktop app. It automatically detects your package manager and creates the appropriate lock file.

Understanding chat.config.ts

The chat.config.ts file controls all feature toggles, branding, and app settings. It’s generated with sensible defaults when you scaffold a project with the CLI.

What the default config includes

The default configuration gives you a minimal, working setup:

Setting	Default	Notes
Gateway	Vercel AI Gateway	Set gateway: "openrouter" for OpenRouter
Authentication	GitHub only	Google and Vercel OAuth disabled
Features	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 — the CLI will tell you exactly which environment variables are needed based on your choices.

Enable features incrementally by editing chat.config.ts and adding the required environment variables. See Configuration for details.

2. Configure Environment Variables

cp .env.example .env.local

After scaffolding, the CLI prints the exact environment variables required for your configuration. Fill in those values in .env.local.

Expand the sections below for setup instructions:

Database (PostgreSQL)

Option A: Neon (generous free tier)

1. Go to Neon
2. Create a project and database
3. Copy the connection string → DATABASE_URL

Option B: Vercel Postgres

1. Go to Vercel Storage
2. Create a new Postgres database
3. 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

AI Gateway

ChatJS supports multiple AI gateways. Pick one:

Option A: Vercel AI Gateway (default)

1. Go to Vercel AI Gateway
2. Create an API key
3. Copy the key → AI_GATEWAY_API_KEY

Option B: OpenRouter

1. Go to OpenRouter
2. Create an API key
3. Copy the key → OPENROUTER_API_KEY

Option C: OpenAI

1. Go to OpenAI API Keys
2. Create an API key
3. Copy the key → OPENAI_API_KEY

Option D: OpenAI Compatible Use any endpoint that follows the OpenAI API format (Ollama, LM Studio, vLLM, Azure).

See Gateways Overview for a full comparison and configuration details.

Authentication (at least one provider required)

GitHub (Recommended)

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

Google

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

Vercel

1. Go to Vercel Integration Console
2. Create a new integration with Sign In with Vercel
3. Copy Client ID → VERCEL_APP_CLIENT_ID
4. Copy Client Secret → VERCEL_APP_CLIENT_SECRET

Blob Storage (Optional)

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

1. Go to Vercel Blob
2. Create a new blob store
3. Copy the token → BLOB_READ_WRITE_TOKEN

To disable, set features.attachments: false and ai.tools.image.enabled: false in chat.config.ts.

3. Push Database Schema

npm run db:push

This pushes the Drizzle schema directly to your database. For production migrations, see deployment guides.

4. Start the Dev Server

npm run dev

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

Deploying to Production

Once you’re running locally, deploy your app:

Vercel

Recommended. Integrated database, blob storage, and AI Gateway.

Docker

Containerized deployment for any platform.

Self-Hosted

Deploy to any Node.js platform.

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 settings in chat.config.ts

AI Capabilities

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

Desktop App

Package your app as a native desktop application with Electron