Visitar URL original
Documenting your adapter | Chat SDK
Chat SDK

Documenting your adapter

Your README is what developers see on npm and GitHub before they install your adapter. Vercel-maintained adapters all use the structure below, so following it lets developers find install steps, credentials, and limitations where they expect them. Community adapters should meet the same bar.

The examples below describe a fictional Matrix adapter. YOUR_PUBLISHED_ADAPTER_PACKAGE is a placeholder, not a package to install. Replace it everywhere, including badges and imports, with the exact npm name of the adapter you own and have published. Verify the installation command and npm links before publishing your README.

README structure

Your README.md should include these sections in order:

Title and badges

Start with the package name as an H1, followed by npm badges and a one-line description.

README.md
# YOUR_PUBLISHED_ADAPTER_PACKAGE

[![npm version](https://img.shields.io/npm/v/YOUR_PUBLISHED_ADAPTER_PACKAGE)](https://www.npmjs.com/package/YOUR_PUBLISHED_ADAPTER_PACKAGE)
[![npm downloads](https://img.shields.io/npm/dm/YOUR_PUBLISHED_ADAPTER_PACKAGE)](https://www.npmjs.com/package/YOUR_PUBLISHED_ADAPTER_PACKAGE)

Matrix adapter for [Chat SDK](https://chat-sdk.dev/docs).

Installation

Show the install command with chat as a co-dependency.

README.md
## Installation

```bash
npm install chat YOUR_PUBLISHED_ADAPTER_PACKAGE
```

Quick start

Give a minimal working example that developers can copy. Call the factory function with explicit config so readers can see which credentials they need.

README.md
## Usage

```typescript
import { Chat } from "chat";
import { createMatrixAdapter } from "YOUR_PUBLISHED_ADAPTER_PACKAGE";

const bot = new Chat({
  userName: "mybot",
  adapters: {
    matrix: createMatrixAdapter({
      homeserverUrl: process.env.MATRIX_HOMESERVER_URL!,
      accessToken: process.env.MATRIX_ACCESS_TOKEN!,
    }),
  },
});

bot.onNewMention(async (thread, message) => {
  await thread.post("Hello from Matrix!");
});
```

Environment variables

List every environment variable your adapter reads, with a description and example value.

README.md
## Environment variables

| Variable | Required | Description |
|----------|----------|-------------|
| `MATRIX_HOMESERVER_URL` | Yes | Matrix homeserver URL (e.g., `https://matrix.example.com`) |
| `MATRIX_ACCESS_TOKEN` | Yes | Bot account access token |
| `MATRIX_BOT_USERNAME` | No | Override the bot display name |

Configuration reference

Document every field in your config interface, including defaults.

README.md
## Configuration

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `homeserverUrl` | `string` | `MATRIX_HOMESERVER_URL` | Matrix homeserver URL |
| `accessToken` | `string` | `MATRIX_ACCESS_TOKEN` | Bot account access token |
| `userName` | `string` | `"matrix-bot"` | Bot display name |
| `logger` | `Logger` | `ConsoleLogger` | Custom logger instance |

Platform setup

Walk through creating the bot account on the platform. Use numbered steps, link to the platform's developer portal, and call out where to find each credential.

README.md
## Platform setup

1. Create a bot account on your Matrix homeserver
2. Generate an access token for the bot
3. Set the webhook URL to `https://your-domain.com/api/webhooks/matrix`

Features

List what your adapter supports. Use a feature table if it helps. Call out any limitations.

README.md
## Features

- Mentions and DMs
- Rich text (bold, italic, code, links)
- Reactions (add and remove)
- File uploads
- Typing indicators
- Thread support

License

README.md
## License

MIT

Code-level documentation

Exported types

Export your config and thread ID interfaces so consumers can use them in their own type annotations. The TypeScript declarations that tsup generates are the main API reference for your adapter, so write interface field comments that are useful in editor hover docs.

src/types.ts
/** Configuration for the Matrix adapter */
export interface MatrixAdapterConfig {
  /** Matrix homeserver URL (e.g., "https://matrix.example.com") */
  homeserverUrl: string;
  /** Access token for the bot account */
  accessToken: string;
  /** Override the bot display name (default: "matrix-bot") */
  userName?: string;
}

TSDoc comments on exported interfaces and functions appear in IDE tooltips and generated .d.ts files. Keep them concise and factual.

What not to document

  • Internal or private methods. They're implementation details.
  • Types re-exported from chat or @chat-adapter/shared. Link to the upstream docs instead.
  • Obvious behavior. postMessage posts a message and needs no further explanation.

Sample messages file

Include a sample-messages.md file in your package root with real webhook payloads from the platform. Contributors use these payloads to reproduce and debug parser edge cases.

sample-messages.md
# Matrix sample messages

## Text message

```json
{
  "type": "m.room.message",
  "room_id": "!abc123:matrix.org",
  "event_id": "$evt456",
  "sender": "@alice:matrix.org",
  "content": {
    "msgtype": "m.text",
    "body": "Hello world"
  },
  "origin_server_ts": 1700000000000
}
```

## Bot mention

```json
{
  "type": "m.room.message",
  "room_id": "!abc123:matrix.org",
  "event_id": "$evt789",
  "sender": "@alice:matrix.org",
  "content": {
    "msgtype": "m.text",
    "body": "@bot help me",
    "format": "org.matrix.custom.html",
    "formatted_body": "<a href=\"https://matrix.to/#/@bot:matrix.org\">bot</a> help me"
  },
  "origin_server_ts": 1700000001000
}
```

Vercel-maintained adapters include a sample-messages.md file in their package roots. Use those as a format reference.

Checklist

Before publishing, verify your documentation covers:

Read more

Publishing your adapter

Package, version, and publish your community Chat SDK adapter to npm.

List a vendor-official adapter

Qualify for the vendor-official tier and add your adapter to the Chat SDK docs, @chat-adapter/catalog, create-chat-sdk, and eve.dev/integrations.

Overview

Overview of Chat SDK adapters, adapter tiers, and where to find platform, state, and catalog guides.

Building an adapter

Learn how to build your own Chat SDK adapter for any messaging platform.

PreviousTesting adaptersNextPublishing your adapter