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

Custom Gateway

Compose a ChatJS app with a third-party gateway registry item

Install a custom gateway when creating your app. If your endpoint implements the OpenAI API, you can also use the built-in OpenAI Compatible gateway.

chat-js create my-chat --gateway https://example.com/r/my-gateway.json
chat-js create my-chat --gateway ./my-gateway.json

Remote registry items and their dependencies require HTTPS. HTTP is supported for loopback development servers only.

Author a registry item

Start from a built-in item in the gateway registry. The authoring contract describes the complete metadata and adapter interface.

Your root item must use type: "registry:item". Declare its SDK in dependencies, and include an adapter exporting Gateway at ~/lib/ai/gateway.ts. Supporting files belong under ~/lib/ai/gateway/ and can come from registryDependencies.

Set meta.chatjs with:

  • kind: "gateway", contractVersion: 1, and a unique literal id.
  • capabilities describing image and video support.
  • Complete defaults for models, workflows, documents, and tools. Use model IDs served by your endpoint.
  • envRequirements, an array of required groups. Each group’s options contains alternative sets of variables.
  • optionalEnv for additional variables the adapter reads.

For example, an endpoint that requires a base URL and accepts an optional API key can declare:

{
  "envRequirements": [{ "options": [["MY_GATEWAY_BASE_URL"]] }],
  "optionalEnv": ["MY_GATEWAY_API_KEY"]
}

This is a metadata fragment, not a complete registry item. Read declared credentials through the adapter’s injected environment, such as this.env.MY_GATEWAY_API_KEY when extending GatewayRuntime from @chat-js/gateways/runtime.

Generated app

The CLI installs the selected adapter and dependencies, then writes lib/ai/gateway-model-defaults.ts with the gateway ID, defaults, capabilities, and environment declarations. lib/env.ts forwards those declared variables to the adapter, and scripts/check-env.ts checks the requirements. You do not add gateway entries to a central application registry or environment schema.

The generated chat.config.ts selects your gateway. Add credentials to .env.local, then verify the app:

bun test:types
bun fetch:models
bun dev

Send a real chat message to verify provider authentication and streaming. Type checks validate the adapter interface and configuration, but cannot verify remote credentials or model availability.

Was this page helpful?