Publishing your adapter

Community adapters are published to npm under your own package name. After publishing, you can list your adapter on the chat-sdk.dev Adapters page.

Package checklist

Before publishing, verify your package.json meets these requirements:

YOUR_PUBLISHED_ADAPTER_PACKAGE is a placeholder for your adapter's npm package name. Replace it with a valid name you own before publishing, and use that exact name in the post-publish verification commands. Do not install the placeholder or an unrelated package with a similar name.

{
  "name": "YOUR_PUBLISHED_ADAPTER_PACKAGE",
  "version": "1.0.0",
  "type": "module",
  "main": "./dist/index.js",
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js"
    }
  },
  "files": ["dist"],
  "peerDependencies": {
    "chat": "^4.0.0"
  },
  "publishConfig": {
    "access": "public"
  },
  "keywords": ["chat-sdk", "chat-adapter", "matrix"],
  "license": "MIT"
}

Naming conventions

Replace PLATFORM and YOUR_SCOPE with your own values. These are naming patterns, not packages to install. New npm package names must be lowercase; see npm's package name rules.

Build and verify

Before publishing, build the package, type-check it, and run the tests.

# Build
npm run build

# Type-check
npm run typecheck

# Run tests
npm test

Inspect the package contents to confirm that only dist/ is included:

npm pack --dry-run

You should see output like:

dist/index.js
dist/index.d.ts
dist/index.js.map
package.json
README.md
LICENSE

If you see src/, node_modules/, or test files in the output, update your "files" field or add a .npmignore.

Versioning

Follow semver:

If a new Chat SDK major version changes your adapter's peer dependency range, bump your adapter's major version too.

Publish to npm

npm publish

For scoped packages published for the first time:

npm publish --access public

Peer dependency compatibility

Your adapter should declare chat as a peer dependency with a caret range:

{
  "peerDependencies": {
    "chat": "^4.0.0"
  }
}

This means your adapter works with any 4.x release. When the Chat SDK ships a new major version:

1. Test your adapter against the new version
2. Update the peer dependency range
3. Publish a new major version of your adapter

Post-publish verification

After publishing, verify the package works for consumers:

# Create a temp directory
mkdir /tmp/test-adapter && cd /tmp/test-adapter
npm init -y

# Install your adapter
npm install chat YOUR_PUBLISHED_ADAPTER_PACKAGE

# Verify the import works
node -e "import('YOUR_PUBLISHED_ADAPTER_PACKAGE').then(m => console.log(Object.keys(m)))"

You should see your exported symbols (createMatrixAdapter, MatrixAdapter, etc.).

Keeping your adapter up to date

• Watch the Chat SDK changelog for new features and breaking changes.
• Run your test suite against new Chat SDK releases before they ship to catch compatibility issues early.
• When the Adapter interface adds new optional methods, consider implementing them to keep your adapter feature-complete.

Listing on chat-sdk.dev

Community adapters can be listed on the Adapters page by opening a PR against the Chat SDK repo that adds a docs page under apps/docs/content/adapters/community/ and an entry in @chat-adapter/catalog. Add the entry as packages/catalog/src/adapters/community/my-adapter.ts and register it in COMMUNITY_ADAPTERS in packages/catalog/src/adapters/index.ts. Your adapter's README is fetched from GitHub at build time and rendered on its dedicated page.

Pin your README to a commit or tag

The docs site re-renders on every deploy, so an unpinned readme would serve whatever is on your default branch at that moment, including edits made after the listing PR was reviewed. Pinning keeps the rendered content at the version we approved. To publish new README content, open a follow-up PR that bumps the ref.

import type { CommunityAdapter } from "../../types";

export const myAdapter = {
  author: "your-github-org",
  description: "One-line summary of what the adapter connects to.",
  features: {
    postMessage: "yes",
    editMessage: "yes",
    streaming: { status: "partial", label: "Post+Edit" },
  },
  group: "community",
  name: "My Adapter",
  packageName: "YOUR_PUBLISHED_ADAPTER_PACKAGE",
  readme: "https://github.com/your-org/chat-adapter-my-thing/tree/v1.2.0",
  slug: "my-adapter",
  type: "platform",
} as const satisfies CommunityAdapter;

The features keys are listed in PLATFORM_FEATURE_CATEGORIES and STATE_FEATURE_CATEGORIES in packages/catalog/src/features.ts. Omitted keys render as unsupported.

Accepted readme formats:

Unpinned refs, such as tree/main or a URL without /tree/<ref>, emit a build warning and are rejected during PR review.