---
title: "Quickstart"
description: "Get ChatJS running in minutes"
---

## Prerequisites

Before you begin, make sure you have:

- **Node.js 22.12+** ([download](https://nodejs.org))
- A package manager: **npm**, **yarn**, **pnpm**, or **bun**

### 1. Create Your Project

Scaffold a new ChatJS app using the CLI:

```bash
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](/platforms/desktop). It preserves `bun`, `pnpm`, and `yarn` when launched from those tools, and defaults `npx`/npm launches to npm.

## 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.

<Accordion>
<AccordionItem title="What the default config includes">
  The default configuration gives you a minimal, working setup:

| Setting | Default | Notes |
| --- | --- | --- |
| **Gateway** | Vercel AI Gateway | Use `create --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](/core/configuration) for details.

</AccordionItem>
</Accordion>

### 2. Configure Environment Variables

```bash
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:

<Accordion>
  <AccordionItem title="Database (PostgreSQL)">
    **Option A: Neon** (generous free tier)
    1. Go to [Neon](https://neon.tech)
    2. Create a project and database
    3. Copy the connection string → `DATABASE_URL`

    **Option B: Vercel Postgres**
    1. Go to [Vercel Storage](https://vercel.com/docs/storage/vercel-postgres/quickstart)
    2. Create a new Postgres database
    3. Copy the connection string → `DATABASE_URL`

    **Option C: Local PostgreSQL**
    ```bash
    # macOS
    brew install postgresql && brew services start postgresql
    createdb chatjs
    # DATABASE_URL=postgres://localhost:5432/chatjs
    ```

  </AccordionItem>
  <AccordionItem title="AI Gateway">
    ChatJS supports multiple AI gateways. Pick one:

    **Option A: Vercel AI Gateway** (default)
    1. Go to [Vercel AI Gateway](https://vercel.com/ai-gateway)
    2. Create an API key
    3. Copy the key → `AI_GATEWAY_API_KEY`

    **Option B: OpenRouter**
    1. Go to [OpenRouter](https://openrouter.ai/keys)
    2. Create an API key
    3. Copy the key → `OPENROUTER_API_KEY`

    **Option C: OpenAI**
    1. Follow the [OpenAI quickstart](https://developers.openai.com/api/docs/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](/gateways/overview) for a full comparison and configuration details.

  </AccordionItem>
  <AccordionItem title="Authentication (at least one provider required)">
    **GitHub (Recommended)**
    1. Go to [GitHub Developer Settings](https://github.com/settings/developers)
    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](https://console.cloud.google.com/apis/credentials)
    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](https://vercel.com/docs/integrations/create-integration)
    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`

  </AccordionItem>
  <AccordionItem title="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](./storage) for provider configuration,
    credentials, and migration behavior.

  </AccordionItem>
</Accordion>

### 3. Push Database Schema

```bash
npm run db:push
```

This pushes the Drizzle schema directly to your database. For production migrations, see [deployment guides](/deployment/vercel).

### 4. Start the Dev Server

```bash
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](/deployment/vercel)**

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

**[Docker](/deployment/docker)**

Containerized deployment for any platform.

**[Self-Hosted](/deployment/self-hosted)**

Deploy to any Node.js platform.

## Troubleshooting

<Accordion>
  <AccordionItem title="Missing environment variables error">
    ChatJS validates env vars at build time. Check `.env.local` has all required
    variables and restart the dev server.
  </AccordionItem>
  <AccordionItem title="Database connection failed">
    Verify `DATABASE_URL` is correct and the database is running. For local
    PostgreSQL, check the service is started.
  </AccordionItem>
  <AccordionItem title="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}`.
  </AccordionItem>
</Accordion>

<Accordion>
<AccordionItem title="Optional Features">
  These environment variables enable additional capabilities:

| Variable | Feature | Setup Guide |
| --- | --- | --- |
| `REDIS_URL` | Resumable streams | [Vercel KV](https://vercel.com/docs/storage/vercel-kv) |
| `TAVILY_API_KEY` | Web search | [Tavily](https://app.tavily.com) |
| `FIRECRAWL_API_KEY` | Web search | [Firecrawl](https://firecrawl.dev) |
| `LANGFUSE_PUBLIC_KEY` | LLM observability | [Langfuse](https://langfuse.com) |
| `LANGFUSE_SECRET_KEY` | LLM observability | [Langfuse](https://langfuse.com) |
| `MCP_ENCRYPTION_KEY` | MCP connectors | `openssl rand -base64 32` (must be exactly 44 chars) |
| `CRON_SECRET` | Cleanup cron job | [Generate](https://generate-secret.vercel.app/32) |

</AccordionItem>
</Accordion>

## Next Steps

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

**[Configuration](/core/configuration)**

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

**[AI Capabilities](/features/overview)**

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

**[Desktop App](/platforms/desktop)**

Package your app as a native desktop application with Electron