chat-js is a free, open source ai interaction & interfaces project written in TypeScript and released under Apache-2.0. It has 1,205 GitHub stars, 123 forks and 40 open issues, and was last pushed 17 hours ago. On this registry it ranks #137 of 167 tracked projects in AI Interaction & Interfaces, with 5 head-to-head comparisons available.

What is chat-js?

ChatJS is an Apache-2.0 TypeScript starter kit for AI chat applications: it scaffolds a working Next.js chat app together with the EVE agent runtime and hands the full source to the developer to brand, extend, and deploy. It is aimed at developers and teams who want to own the code of their AI interface rather than rent one.

What it is

ChatJS lives in the Next.js and TypeScript ecosystem, pairing a shadcn/ui front end — scaffolded with either Base UI or Radix — with a PostgreSQL-backed application layer and Better Auth for sign-in. On top of that sits EVE, a durable agent runtime that runs conversations and tools, persists execution state, handles approvals, and lets a client reconnect to a response that is still in progress. The repository ships the reference app, the site and browser builder, the documentation, an Electron companion, the CLI, and a source registry.

The concrete problem it solves is the blank page. Instead of assembling streaming responses, saved conversations, authentication, database migrations, and agent execution from scratch, a developer starts from something that already runs and edits it. Tools and plugins arrive as source files that can be edited and committed with the app, and configuration lives in named files: branding, model defaults, and app settings in chat.config.ts, agent behavior in agent/agent.ts.

Key capabilities

  • Scaffolding through npx chat-js@alpha create my-app, which asks interactively which gateway, authentication providers, and optional features to include; a browser builder at chatjs.dev/create previews the UI and produces a tailored command.
  • The EVE durable agent runtime, which persists execution state, handles tool approvals, and lets clients reconnect to an in-progress response.
  • Model access through Vercel AI Gateway, OpenRouter, OpenAI, LiteLLM, or any OpenAI-compatible endpoint.
  • Optional capabilities added at scaffold time or later: uploads, projects, and sharing, plus agent tools for web search, code execution, image generation, and MCP connectors.
  • npx chat-js@alpha add mcp installs MCP connectors, with MCP_ENCRYPTION_KEY set in .env.local; schema changes flow through npm run db:generate and npm run db:migrate.
  • Deployment to Vercel, Docker, or Node.js for the web app, with an Electron companion packaging the same app for macOS, Windows, and Linux.

Who uses it and how

  • Teams that want to commit tools and plugins into their own repository instead of extending a hosted product through someone else's extension system.
  • Self-hosters running the web app under Docker or Node.js against their own PostgreSQL instance and their own gateway credentials.
  • Teams shipping a desktop client, using the Electron companion to package for macOS, Windows, and Linux.
  • Developers comparing providers, who point the same app at different gateways without rewriting the chat layer.
  • Contributors working inside the monorepo on the reference app, site and builder, docs, CLI, or source registry, using bun lint and bun test:types before a pull request.

Getting started

Run npx chat-js@alpha create my-app with Node.js 24 or newer, copy .env.example to .env.local, fill in the PostgreSQL connection along with gateway and authentication credentials, then run npm run setup and npm run dev and open localhost:3000. AUTH_SECRET and EVE_GATEWAY_SECRET are generated separately with openssl rand -base64 32.

How it compares

The facts supplied for this entry name no paid products that ChatJS replaces and no directly similar chat scaffolds, so it stands alone in this registry. Its nearest point of contrast is provider neutrality: rather than tying the app to a single vendor, it routes model traffic through whichever gateway the developer configures.

When to use it — and when not to

Self-hosting means operating PostgreSQL, generating and safeguarding AUTH_SECRET, EVE_GATEWAY_SECRET, and MCP_ENCRYPTION_KEY, and supplying gateway credentials, so anyone unwilling to run that infrastructure should look elsewhere. ChatJS 1.0 is in alpha, meaning APIs, configuration, and generated code may change before the stable release, and teams that need a frozen, long-supported foundation should wait or pin carefully. It is a scaffold rather than a managed product, so the generated code becomes yours to maintain.

project readme (upstream, from github) — read inline

ChatJS

The building blocks for your AI app.

Start with a working AI chat. Choose your models and tools. Own the code.

Create an app · Try the demo · Read the docs

ChatJS 1.0 is in alpha. Use chat-js@alpha to try it. APIs, configuration, and generated code may change before the stable release.

Quickstart

Use Node.js 24 or newer. You can scaffold interactively from the terminal. The browser builder lets you preview the UI, configure the agent, and copy a tailored command. Open the builder

npx chat-js@alpha create my-app
cd my-app
cp .env.example .env.local

The CLI asks which gateway, authentication providers, and optional features to include. Fill in .env.local with your PostgreSQL connection, gateway and authentication credentials, and any settings required by your selections. Generate AUTH_SECRET and EVE_GATEWAY_SECRET separately with openssl rand -base64 32. Full setup guide

npm run setup
npm run dev

The setup command applies app migrations and prepares EVE's workflow database. Open localhost:3000 to sign in and send your first message.

What you get

  • A working chat app. Next.js, TypeScript, and shadcn/ui with streaming responses, saved conversations, and Better Auth. Scaffold with Base UI or Radix.
  • A durable agent runtime. EVE runs conversations and tools, persists execution state, handles approvals, and lets the client reconnect to an in-progress response. Architecture
  • Your choice of models. Use Vercel AI Gateway, OpenRouter, OpenAI, LiteLLM, or an OpenAI-compatible endpoint. Gateways
  • Optional capabilities. Add uploads, projects, and sharing, or equip the agent with web search, code execution, image generation, or MCP connectors. Tools · Plugins

Make it yours

Change branding, model defaults, and app settings in chat.config.ts. Customize agent behavior in agent/agent.ts. Tools and plugins are installed as source files you can edit and commit with your app. Source ownership

To add MCP connectors, run this from inside your app.

npx chat-js@alpha add mcp

Generate MCP_ENCRYPTION_KEY with openssl rand -base64 32 and set it in .env.local. Run npm run db:generate, review the generated SQL, then apply it with npm run db:migrate. MCP setup · CLI reference

Deploy the web app on Vercel or self-host it with Docker or Node.js. Add the Electron companion to package your app for macOS, Windows, and Linux. Deployment guides · Desktop guide

Contributing

This repository contains the reference app, site and builder, docs, Electron companion, CLI, and source registry.

For a fresh checkout, use Node.js 24+ and Bun from the repository root.

bun install
cp apps/chat/.env.example .env.local
# Fill in the environment variables for the reference app.
bun run setup
bun dev

Use bun dev:info to find your local app URLs and bun dev:docs to work on the docs. For unattended local development on macOS, bun dev:service start registers supervision at login. Use bun dev:health to check readiness and bun dev:service stop to unregister it.

For registry changes, edit packages/registry/src and the relevant manifests. The development server mirrors them into apps/chat. Run bun lint, bun test:types, and the relevant tests before opening a PR. Repository instructions · Registry development · Release process

License

Apache 2.0

Vercel OSS Program

Frequently asked questions

Is chat-js free to use?

chat-js is open source under the Apache-2.0 licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does chat-js do?

The building blocks for your AI app.

What is chat-js written in?

chat-js is primarily written in TypeScript. Its source is publicly available at https://github.com/FranciscoMoretti/chat-js, and it has 1,205 GitHub stars.