Skip to main content
The ChatJS tool registry is the distribution layer for installable tools. It lets you ship a tool’s server logic, UI renderer, and supporting files as a portable package that another ChatJS app can install with chatjs add. This is the extension surface for ChatJS. Built-in product tools stay in tools/platform. Installable tools live in tools/chatjs and are managed by the CLI.

​
What You Install

When you run chatjs add, the CLI:
  1. Fetches a registry item by name
  2. Resolves any registry dependencies that item depends on
  3. Writes the tool files into the installable tools directory from chat.config.ts
  4. Installs any npm dependencies declared by the registry item
  5. Warns if installed items declare missing environment variables
  6. Updates the CLI-managed registry files so the tool is available to the model and renderer
npx @chat-js/cli@latest add word-count

​
Why This Exists

The registry gives ChatJS a standardized way to distribute software between projects.
  • You can publish self-contained tools instead of copying app-specific code by hand.
  • Installed tools become part of the app’s typed tool system automatically.
  • Each tool can ship both execution logic and a custom UI renderer.
  • Shared helpers can be distributed as registry dependencies and installed alongside the main tool.
If you have used shadcn/ui, the model is similar. The registry distributes source files into your project instead of mounting opaque runtime plugins.

​
Installed Tool Layout

By default, installed tools are written into tools/chatjs: 
tools/
  chatjs/
    tools.ts
    ui.ts
    word-count/
      tool.ts
      renderer.tsx
    _shared/
      hooks/
      lib/
tools/chatjs/tools.ts and tools/chatjs/ui.ts are the CLI-managed registry files. You should not edit them manually.

​
Registry Boundaries

ChatJS separates tools into two layers:
LocationOwnershipPurpose
tools/platformChatJS platformBuilt-in product tools and tightly coupled internal tooling
tools/chatjsRegistry + appInstallable tools distributed through chatjs add
Use tools/platform when a tool depends on internal app contracts or product infrastructure. Use tools/chatjs when a tool should be portable across ChatJS projects as a distributable package.

​
Project Configuration

The registry installs files into the path configured by paths.tools in chat.config.ts:
chat.config.ts
export default defineConfig({
  paths: {
    tools: "@/tools/chatjs",
  },
});
The CLI uses this path both to decide where files should be written and which import alias should be used inside the generated registry index.

​
Tool Environment Variables

Installable tools can declare their own environment requirements directly in tool.ts.
tools/chatjs/retrieve-url/tool.ts
import type { ToolEnvVars } from "@chat-js/registry";

export const toolEnvVars: ToolEnvVars = [
  {
    options: [["FIRECRAWL_API_KEY"]],
  },
];
The registry build extracts toolEnvVars into the generated registry manifest as envRequirements. chatjs add uses that metadata for install-time warnings, and check-env validates installed tools from their tool.ts source at app startup and build time.

​
Using a Different Registry

You can point the CLI at a local or custom registry: 
npx @chat-js/cli@latest add word-count \
  --registry ./packages/registry/items/{name}.json \
  --cwd apps/chat
You can also set a default registry URL template with CHATJS_REGISTRY_URL.

​
Manual Update And Troubleshooting

  • Re-running chatjs add is safe. The CLI avoids duplicate registry entries.
  • Pass --overwrite if you want to replace existing installed files.
  • If chat.config.ts is missing, chatjs add will stop before making changes.
  • If an item declares shared registry dependencies, those are installed automatically before the main item is registered.
  • If the registry index does not exist yet, the CLI creates it for you.
  • CLI add for the command reference
  • Adding Tools for how installation works under the hood
  • Tools for authoring and publishing registry tools