--- title: Documenting your adapter description: Write a README, configuration reference, and usage examples for your adapter. type: guide prerequisites: - /docs/contributing/building - /docs/contributing/testing related: - /docs/contributing/publishing - /docs/contributing/vendor-official - /docs/adapters --- # 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. ```markdown title="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. ````markdown title="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. ````markdown title="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. ```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. 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. ```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; } ``` 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. ````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": "bot 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: * [ ] 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 --- For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md) For an index of all available documentation, see [/llms.txt](/llms.txt) For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)