Publishing your adapter

Package checklist

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

{
  "name": "chat-adapter-matrix",
  "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

Build and verify

Run a full build and verify everything compiles before publishing.

# Build
npm run build

# Type-check
npm run typecheck

# Run tests
npm test

Inspect the package contents to make sure 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:

When the Chat SDK releases a new major version, you'll need a major bump too if your adapter's peer dependency range changes.

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

# Verify the import works
node -e "import('chat-adapter-matrix').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 that adds an entry to apps/docs/adapters.json in the Chat SDK repo. 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 currently sits at your default branch — including edits made after the listing PR was reviewed. Pinning freezes the rendered content at the state we approved; new content goes live through a follow-up PR that bumps the ref.

{
  "name": "My Adapter",
  "slug": "my-adapter",
  "type": "platform",
  "community": true,
  "packageName": "chat-adapter-my-thing",
  "readme": "https://github.com/your-org/chat-adapter-my-thing/tree/v1.2.0"
}

Accepted readme formats:

Unpinned refs (e.g., tree/main, or omitting /tree/<ref> entirely) will emit a build warning and are rejected during PR review.