Publishing your adapter

Package checklist

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

package.json

{
  "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"
}

Field	Why it matters
`"type": "module"`	ESM-only — matches the Chat SDK ecosystem
`"files": ["dist"]`	Only publish compiled output, keeping the package lean
`"exports"`	Explicit entry points for bundlers and Node.js
`"peerDependencies"`	Consumers provide their own `chat` instance
`"publishConfig"`	Required for scoped packages (`@your-scope/chat-adapter-*`)
`"keywords"`	Include `chat-sdk` and `chat-adapter` for npm discoverability

Naming conventions

Convention	Example	When to use
Unscoped	`chat-adapter-matrix`	Most community adapters
Scoped	`@your-org/chat-adapter-matrix`	Optional — if you prefer publishing under your org's scope

The @chat-adapter/ npm scope is reserved for Vercel-maintained adapters. Do not publish under this scope.

Build and verify

Run a full build and verify everything compiles before publishing.

Terminal

# Build
npm run build

# Type-check
npm run typecheck

# Run tests
npm test

Inspect the package contents to make sure only dist/ is included:

Terminal

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:

Change	Bump	Example
Bug fix, internal refactor	`patch`	`1.0.0` → `1.0.1`
New feature, new export, new config option	`minor`	`1.0.0` → `1.1.0`
Breaking change (removed export, changed signature)	`major`	`1.0.0` → `2.0.0`

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

Terminal

npm publish

For scoped packages published for the first time:

Terminal

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:

Test your adapter against the new version
Update the peer dependency range
Publish a new major version of your adapter

Post-publish verification

After publishing, verify the package works for consumers:

Terminal

# 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

Publishing your adapter

On this page