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

Configuration & Extensions

Install capabilities and configure runtime policy in ChatJS

ChatJS separates installed source, runtime policy, and deployment infrastructure. The CLI installs plugins, tools, and selected gateway, storage, and sandbox providers. chat.config.ts supplies branding, model defaults, authentication settings. Environment variables supply credentials and deployment connections.

Extension types

Type What you select Documentation
Core App behavior such as conversations, authentication, and parallel responses Architecture
Plugins Optional app integrations such as Projects, Credits, and MCP Plugins
Tools Model-facing operations such as search, execution, and document editing Tools
Gateway Inference and model discovery Models & Gateways
Storage Files SDK adapter for durable files File Storage
Sandbox Execution infrastructure and persistent EVE session files where supported Sandboxes

Runtime settings configure the source you installed. They do not install missing capabilities. See Source Ownership before customizing that source.

Runtime configuration

The generated chat.config.ts is parsed by lib/config-schema.ts and exported as config from @/lib/config. Use the installed gateway’s discriminator and override only the settings you need. This example applies to a Vercel gateway installation with deep-research and followup-suggestions installed:

import type { ConfigInput } from "@/lib/config-schema";

const config = {
  appName: "Your App Name",
  appPrefix: "your-app",
  organization: {
    name: "Your Company",
    contact: {
      privacyEmail: "privacy@example.com",
      legalEmail: "legal@example.com",
    },
  },
  ai: {
    gateway: "vercel",
    tools: {
      followupSuggestions: { enabled: true, default: "openai/gpt-5-nano" },
      deepResearch: {
        defaultModel: "google/gemini-2.5-flash-lite",
        finalReportModel: "google/gemini-3-flash",
        allowClarification: true,
        maxResearcherIterations: 1,
        maxConcurrentResearchUnits: 2,
        maxSearchQueries: 2,
      },
    },
  },
  features: { parallelResponses: true },
  authentication: { google: false, github: true, vercel: false },
} satisfies ConfigInput;

export default config;

You keep one editable chat.config.ts. Each installed tool supplies its schema and defaults through the generated chatjs/generated/installed-config.ts. Its options appear in the inferred input type only while it is installed. Remove its overrides when removing a tool.

Model settings do not install their tools. Follow-up suggestions retain an enabled runtime setting. Search, retrieval, code execution, image/video generation and deep research do not have enabled configuration fields.

Install capabilities

Run commands inside your generated app, using the CLI version appropriate to your installation:

bunx chat-js@alpha add tavily-search deep-research
bunx chat-js@alpha add code-documents saved-code-execution --sandbox-provider vercel
bunx chat-js@alpha add attachment-uploads --storage-provider vercel-blob --sandbox-provider vercel
bunx chat-js@alpha add mcp
Installation Requirements
tavily-search or firecrawl-search Selected provider’s credentials. One webSearch provider serves chat and research.
deep-research Text documents, document reading and a search provider. Missing search defaults to Tavily.
saved-code-execution Code documents, document reading and a compatible codeExecution provider. Missing execution installs the built-in code-execution tool, which requires sandbox infrastructure. Select --sandbox-provider if none is installed.
generate-image / generate-video Compatible gateway capability, a default media model and persistent storage. Only the built-in Vercel gateway declares video support.
attachment-uploads Persistent storage and a sandbox with persistent-file support. Configure limits separately under attachments.
mcp MCP_ENCRYPTION_KEY, including installations with no connectors yet.
vercel-analytics, vercel-speed-insights, langfuse Independently installed telemetry. Langfuse requires its keys.

Planning resolves transitive registry dependencies and validates the resulting selection before installation. Memory storage is appropriate only when no installed feature needs persistent files. An external adapter’s metadata is a declaration, not proof of live provider behavior.

Replace providers

Gateway selection installs chatjs/providers/gateway.ts and its typed defaults. Changing only ai.gateway cannot switch providers:

bunx chat-js@alpha add --gateway openai --replace
bunx chat-js@alpha add firecrawl-search --replace
bunx chat-js@alpha add tavily-search --replace

Replacement requires --replace. Modified or untracked provider source requires review and explicit --overwrite. Keep a version-control checkpoint before replacing customized source. The CLI preserves runtime model overrides, so review their IDs for the selected gateway and run bun run setup and bun run fetch:models after supplying credentials. Registry addresses can select external providers too. The CLI removes unused dependency entries that its installation receipt owns, and refreshes its marked environment-example sections. It preserves pre-existing dependencies, user-changed versions, dependencies referenced by remaining source and environment entries outside those sections. ChatJS supports new installations rather than upgrades from older templates.

Search replacement uses the same webSearch slot for direct search and research. Saved-code execution requires an executor export, in addition to a codeExecution tool. The built-in Vercel and Daytona adapters support code execution. Persistent session files require Vercel or a compatible external provider. Hosted lifecycle validation is separate from adapter selection. See Self-hosted deployment for the infrastructure acceptance boundary.

A reproducible minimal scaffold omits document tools as well as optional integrations:

bunx chat-js@alpha create minimal-chat --yes --no-documents --no-mcp --no-attachments --no-electron

Runtime policy and credentials

Authentication booleans enable GitHub, Google or Vercel OAuth and require the corresponding credentials. Install Guest Chat for disposable visitor sessions. Its server-owned policy controls the model, input size, expiry, and IP limits. Guests have no credit balance. Retention additionally needs an operational cleanup schedule and lifecycle support.

features.parallelResponses controls parallel responses. attachments.acceptedTypes, maxBytes and maxDimension control installed upload behavior. Neither setting installs its feature. Branding, organization/legal text and pricing display are also runtime configuration.

Read installed descriptors and .env.example for credentials, then run bun run check-env. Never put secrets in chat.config.ts or --storage-config. See Config reference and Gateway overview.

Last updated on Nov 8, 2026

Was this page helpful?