---
title: "Configuration"
description: "Customize ChatJS via chat.config.ts"
---

All feature toggles and app settings live in `chat.config.ts`. It is parsed and exported as `config` from `@/lib/config`.

## Config Structure

```typescript title="chat.config.ts"
import type { ConfigInput } from "@/lib/config-schema";

const config: ConfigInput = {
  appName: "Your App Name",
  appPrefix: "your-app",

  organization: {
    name: "Your Company",
    contact: {
      privacyEmail: "privacy@example.com",
      legalEmail: "legal@example.com",
    },
  },

  ai: {
    gateway: "vercel", // "vercel" | "openrouter" | "openai" | "openai-compatible"
    tools: {
      webSearch: { enabled: true },
      urlRetrieval: { enabled: true },
      codeExecution: { enabled: true },
      mcp: { enabled: false },
      followupSuggestions: { enabled: true, default: "openai/gpt-5-nano" },
      image: { enabled: true },
      video: { enabled: true },
      deepResearch: {
        enabled: true,
        defaultModel: "google/gemini-2.5-flash-lite",
        finalReportModel: "google/gemini-3-flash",
        allowClarification: true,
        maxResearcherIterations: 1,
        maxConcurrentResearchUnits: 2,
        maxSearchQueries: 2,
      },
    },
  },

  features: {
    attachments: true, // File uploads (images and PDFs)
  },

  authentication: {
    google: true,
    github: true,
    vercel: false,
  },

  // ... more options
};

export default config;
```

## AI Gateway

The `ai.gateway` field selects which AI backend to use. All model routing, fetching, and API calls go through the active gateway.

| Value | Backend | Env Dependency |
| --- | --- | --- |
| `"vercel"` (default) | [Vercel AI Gateway](/gateways/vercel) | `AI_GATEWAY_API_KEY` or `VERCEL_OIDC_TOKEN` |
| `"openrouter"` | [OpenRouter](/gateways/openrouter) | `OPENROUTER_API_KEY` |
| `"openai"` | [OpenAI](/gateways/openai) | `OPENAI_API_KEY` |
| `"openai-compatible"` | [OpenAI Compatible](/gateways/openai-compatible) | `OPENAI_COMPATIBLE_BASE_URL` |
| `"litellm"` | [LiteLLM](/gateways/litellm) | `LITELLM_BASE_URL` |

```typescript
ai: {
  gateway: "openrouter", // Switch to OpenRouter
  // ...
},
```

See [Gateways](/gateways/overview) for detailed setup and comparison.

## Features

Toggle feature flags on/off. Tool flags live under `ai.tools.*.enabled`. Application-level flags live under `features`. Missing env vars are caught at build time via `bun run prebuild`.

| Feature | Config Key | Env Dependency |
| --- | --- | --- |
| Code Execution | `ai.tools.codeExecution.enabled` | `VERCEL_OIDC_TOKEN` (on Vercel) or `VERCEL_TEAM_ID + VERCEL_PROJECT_ID + VERCEL_TOKEN` |
| Web Search | `ai.tools.webSearch.enabled` | `TAVILY_API_KEY` or `FIRECRAWL_API_KEY` |
| URL Retrieval | `ai.tools.urlRetrieval.enabled` | `FIRECRAWL_API_KEY` |
| MCP Connectors | `ai.tools.mcp.enabled` | `MCP_ENCRYPTION_KEY` |
| Image Generation | `ai.tools.image.enabled` | Configured file storage provider |
| Video Generation | `ai.tools.video.enabled` | Configured file storage provider |
| Deep Research | `ai.tools.deepResearch.enabled` | `TAVILY_API_KEY` or `FIRECRAWL_API_KEY` |
| Follow-up Suggestions | `ai.tools.followupSuggestions.enabled` | Uses your configured language model provider |
| Attachments | `features.attachments` | Configured file storage provider |
| Parallel Responses | `features.parallelResponses` | None |

```typescript
ai: {
  tools: {
    webSearch: { enabled: true },          // Requires TAVILY_API_KEY or FIRECRAWL_API_KEY
    urlRetrieval: { enabled: false },      // Requires FIRECRAWL_API_KEY
    codeExecution: { enabled: true },      // Vercel-native
    mcp: { enabled: false },               // Requires MCP_ENCRYPTION_KEY
    image: { enabled: true },              // Requires durable file storage
    video: { enabled: false },             // Requires durable file storage
    deepResearch: { enabled: false },      // Requires search provider
    followupSuggestions: { enabled: true } // Uses selected provider/model
  },
},
features: {
  attachments: true, // Requires durable file storage
  parallelResponses: true,
},
```

## Authentication

Set to `true` to enable providers. Missing env vars are caught at server startup.

```typescript
authentication: {
  google: false, // Requires AUTH_GOOGLE_ID + AUTH_GOOGLE_SECRET
  github: true,  // Requires AUTH_GITHUB_ID + AUTH_GITHUB_SECRET
  vercel: false, // Requires VERCEL_APP_CLIENT_ID + VERCEL_APP_CLIENT_SECRET
},
```

## Branding

Customize app name and organization details:

```typescript
appName: "ChatJS",
appTitle: "ChatJS - The prod ready AI chat app",
appPrefix: "chatjs",

organization: {
  name: "Your Company",
  contact: {
    privacyEmail: "privacy@example.com",
    legalEmail: "legal@example.com",
  },
},
```

## Deep Research

Configure the deep research pipeline in `ai.tools.deepResearch`:

```typescript
ai: {
  tools: {
    deepResearch: {
      enabled: true,                   // Requires webSearch provider config
      defaultModel: "openai/gpt-5-mini",
      finalReportModel: "openai/gpt-5-mini",
      allowClarification: true,        // Ask clarifying questions before starting
      maxResearcherIterations: 1,      // Supervisor loop iterations
      maxConcurrentResearchUnits: 2,   // Topics researched in parallel
      maxSearchQueries: 2,             // Queries per research topic
    },
  },
},
```

See [Deep Research](/features/deep-research) for usage details.

## Using Config in Components

Import directly in both server and client components:

```typescript
import { config } from "@/lib/config";

export function MyComponent() {
  return <div>{config.appName}</div>;
}
```

See [Config Reference](/reference/config) for full type definitions.