---
title: Documenting your adapter
description: Write a README, configuration reference, and usage examples for your community adapter.
type: guide
prerequisites:
  - /docs/contributing/building
  - /docs/contributing/testing
related:
  - /docs/contributing/publishing
  - /docs/adapters
---

## 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.

````markdown title="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.

````markdown title="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.

````markdown title="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.

````markdown title="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.

````markdown title="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.

````markdown title="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.

````markdown title="README.md"
## Features

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

### License

````markdown title="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. 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.

```typescript title="src/types.ts" lineNumbers
/** 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;
}
```

<Callout type="info">
  TSDoc comments on exported interfaces and functions appear in IDE tooltips and generated `.d.ts` files. Keep them concise and factual.
</Callout>

### 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.

````markdown title="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