Documenting your adapter

Write a README, configuration reference, and usage examples for your community adapter.

Why documentation matters

Your adapter's README is the first thing developers see on npm and GitHub. Clear documentation reduces support questions, builds trust, and encourages adoption.

All Vercel-maintained adapters follow a consistent structure. Community adapters should aim for the same bar.

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

# chat-adapter-matrix

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

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 chat-adapter-matrix
```

Quick start

A minimal working example that developers can copy-paste. Include the factory function with explicit config so readers understand what credentials are needed.

README.md

## Usage

```typescript
import { Chat } from "chat";
import { createMatrixAdapter } from "chat-adapter-matrix";

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

Export your config and thread ID interfaces so consumers can use them in their own type annotations. TypeScript declarations generated by tsup serve as the primary API reference — keep your interface fields descriptive enough that hover-over docs in an editor are useful.

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/private methods — they're implementation details
Re-exported types from chat or @chat-adapter/shared — link to the upstream docs instead
Obvious behavior — postMessage posts a message, no need to elaborate

Sample messages file

Include a sample-messages.md file in your package root with real webhook payloads from the platform. This is invaluable for other contributors debugging 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
}
```

Existing Vercel-maintained adapters include sample-messages.md files in their package roots — check those for format reference.

Checklist

Before publishing, verify your documentation covers:

README with badges, install, quick start, env vars, config reference, platform setup
TSDoc comments on all exported interfaces and factory functions
sample-messages.md with real platform webhook payloads
Links to Chat SDK docs (chat-sdk.dev) where relevant

Documenting your adapter

Why documentation matters

README structure

Title and badges

Installation

Quick start

Environment variables

Configuration reference

Platform setup

Features

License

Code-level documentation

Exported types

What not to document

Sample messages file

Checklist

On this page