ChatJS: A Production-Ready AI Chat Foundation for TypeScript Teams

The Problem: Rebuilding the Same Chat Infrastructure Every Time

Most teams building an AI chat product start from nothing and wire up the same set of pieces: an authentication layer, a way to call multiple AI providers, a database to store conversation history, streaming to the client, and some mechanism to recover from dropped connections. Each of those pieces takes time to get right independently, and the choices compound: swap the auth provider and the database schema changes; add a second model provider and the streaming logic branches. Teams routinely spend weeks on infrastructure before writing a single line of product-specific code.

ChatJS addresses this by shipping all of those pieces together as a single opinionated scaffold. The README describes the goal as giving teams an EVE-native foundation with authentication, models, streaming, and tools so they can focus on what makes their app unique. The practical result is a monorepo with a working chat application, a landing page, documentation, and a CLI scaffold tool, all versioned together and tested as a system. This is not a minimal boilerplate but a complete application that happens to be open source.

The EVE Runtime: How Conversations Stay Durable

The single most significant architectural choice in ChatJS is that every conversation runs through EVE. EVE is the sole runtime for conversation state: it owns the durable transcript, execution state, approval flows, checkpoints, and stream recovery. ChatJS wraps EVE with authenticated access, conversation metadata, project management, sharing, file handling, and billing evidence, but it does not maintain a parallel conversation store.

What this means in practice: if a streaming response is interrupted mid-generation, EVE can resume it from a checkpoint rather than requiring the client to restart the request. If a tool call requires human approval before proceeding, EVE holds the execution state while the approval is pending, then continues from that point. These capabilities are not available with a simple database-backed approach and represent a meaningful engineering investment that ChatJS provides out of the box.

The README is explicit about one hard boundary: historical ChatJS conversations, from deployments before the EVE migration, are not imported into EVE. Any deployment upgrading from an earlier version of the project loses that conversation history. The migration report at docs/eve-migration-report.md documents the current boundary and what remains as a release gate, including provider deletion coverage and guest-hosting readiness. Two items are explicitly called out as unfinished release gates, not stable features.

Scaffolding a New App with the CLI

The fastest path to a running ChatJS application is the CLI. The command below creates a new project directory:

npx @chat-js/cli@latest create my-app

The CLI walks through gateway selection, feature choices, and authentication configuration. It generates chat.config.ts and outputs a list of environment variables your selections require. You must provision those variables manually before the application can start.

The chat application runs in development mode with:

bun dev

This starts the Next.js application with the local EVE runtime attached. Local EVE development requires Node 24 or later, Bun, and Postgres databases configured for both ChatJS and EVE. The CHATJS_DEV_SLOT variable in .env.worktree.local reserves a stable port range per worktree, with the chat application at offset 0 within that range. Running bun dev:info prints the assigned URLs for the current worktree without guessing.

For teams running multiple simultaneous worktrees on macOS, the launchd service mode is available:

bun dev:service start
bun dev:health

bun dev:service start registers the checkout under launchd supervision and starts it at login. bun dev:health performs a bounded readiness check against ChatJS, EVE, and the databases. The supervisor polls readiness every ten seconds and gives the application up to ten minutes on slow compilation. Logs go to ~/Library/Logs/ChatJS/.

Monorepo Layout and Development Workflow

The monorepo contains four main packages. apps/chat is the Next.js chat application served publicly at demo.chatjs.dev. apps/site is the landing page at chatjs.dev. apps/docs is the documentation site built with Blume. packages/cli is the @chat-js/cli package that is published to npm and used to scaffold new projects.

All packages share Oxlint and Oxfmt configuration through the Ultracite preset. The top-level lint command checks Oxlint rules, Oxfmt formatting, and documentation health in a single pass. Releases are managed through Changesets: each releasable package change needs a changeset file, and merging the generated version PR from the Changesets workflow triggers publishing. The @chat-js/cli package publishes to npm; the Electron desktop package publishes to GitHub Releases.

Development tools are additive rather than always-on. The bun dev:query variant enables React Query Devtools. bun dev:scan enables React Scan. bun dev:debug enables both. Switching between them requires stopping the dev server and reloading the page, but neither tool requires reinstalling. The project also ships .claude/, CLAUDE.md, AGENTS.md, and .codex/ directories, which indicates the codebase is maintained with AI coding assistant workflows as part of its standard tooling.

Features: Models, Branching, Sharing, and Desktop Packaging

ChatJS routes model requests through AI Gateway, which provides access to over 120 models including Claude, GPT-series, Gemini, and Grok through a single API endpoint. Changing the model in a conversation does not require touching the transport layer because the routing is handled at the gateway level.

Conversation branching lets users fork an existing conversation at any message and explore an alternative path without losing the original thread. Shared conversations can be published with public links. The web search integration connects to real-time search results as a tool within a conversation. Image generation and sandboxed code execution are available as built-in tools. Model Context Protocol support means external data sources and tools can be connected using the MCP standard without custom integration code.

The Electron integration packages the chat application as a native desktop app for macOS, Windows, and Linux. For teams that need to distribute a standalone product rather than a web service, the desktop path is part of the monorepo rather than a separate repository. The Electron port occupies offset 1 within the worktree port range, adjacent to the web application at offset 0.

Hard Constraints and Cases Where ChatJS Is the Wrong Starting Point

ChatJS is tightly coupled to EVE. You cannot replace the EVE runtime with a simpler database-backed conversation store without rebuilding significant portions of the application. This is a deliberate trade-off for durability and recovery, but it means the EVE gateway secret and the Workflow World Postgres configuration must be in place before local development is possible.

The stack is substantial. PostgreSQL, Bun, Node 24, Vercel Blob for file storage, and Langfuse for observability are all dependencies in the default scaffold. A team that wants a minimal chat UI backed by a single model with no conversation persistence will spend more effort disabling things than enabling them.

As a direct alternative for minimal setups, Vercel's Next.js AI Chatbot template covers streaming and basic model calls with fewer infrastructure dependencies. It does not include EVE's durable conversation primitives, branching, or the full feature set, but it has no Bun requirement and no EVE gateway dependency. ChatJS is the right choice when you intend to use the full system; Vercel's AI Chatbot is better when you need only the transport layer.

The README also notes that provider deletion coverage and guest-hosting readiness remain release gates. These are not finished features. A team building a product that requires guest user access or needs provable provider data deletion should read docs/eve-migration-report.md before committing to ChatJS in production.

Maintenance State and License

The last push to the repository was on 2026-09-27, one day before this article was written, and recent releases include @chat-js/[email protected] from September 2026. The repository is under active development. The license is Apache-2.0, which permits commercial use, modification, and distribution with the requirement to include the license and a NOTICE file. A NOTICE file is present in the repository root.

The Changesets-driven release process means version history is managed deliberately rather than through ad hoc commits. The presence of a CHAT_RUNTIME_MIGRATION_PLAN.md and a migration report document suggests the team tracks architectural decisions in the repository rather than only in external systems. Teams adopting ChatJS should monitor the migration report and the release notes for changes to the EVE boundary, which is the part of the system most likely to affect upgrade paths.

Editorial conclusion

ChatJS suits TypeScript teams that want a deployable AI chat product without spending weeks assembling authentication, model routing, and conversation persistence from scratch. Teams unfamiliar with EVE, Bun, or the durable conversation model will need to invest time in the toolchain before they can build on top of it. Before committing, verify that the EVE gateway configuration and the required Postgres databases can be provisioned in your environment, and read docs/eve-migration-report.md for the current boundary between what ChatJS owns and what EVE owns.

Frequently asked questions

Official sources

1. FranciscoMoretti/chat-js on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases