Skip to content
ChatJS
Esc
↑↓navigate↵open⌘Jpreview
On this page

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 a Desktop app. It preserves bun, pnpm, and yarn when launched from those tools, and defaults npx/npm launches to npm unless you pass --package-manager.

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. Follow the OpenAI quickstart to create an API key
  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
File Storage (Optional)

Required for file attachments, image generation, and video generation. The installer asks you to select a Files SDK provider when you enable one of these capabilities.

Configure the environment variables printed by the CLI for your selected provider. For Vercel Blob, connect a Blob store and copy its token to BLOB_READ_WRITE_TOKEN for local development.

See File storage for provider configuration, credentials, and migration behavior.

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

Was this page helpful?