chat
Version:
Unified chat abstraction for Slack, Teams, Google Chat, and Discord
219 lines (161 loc) • 6.27 kB
text/mdx
---
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
[](https://www.npmjs.com/package/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 `-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