Publishing a Plugin

Once you have built a plugin, you may want to share it with others. This guide covers packaging, publishing, and documentation best practices.

The workflow is:

Build your plugin as an npm package
Publish it to npm (or a private registry)
Users install it with npm install or pnpm add
Users load it via the plugins array in wa.config.js

Package Structure

package.json

{
  "name": "@myorg/my-plugin",
  "version": "1.0.0",
  "description": "A plugin that does X",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "types": "./dist/index.d.ts"
    }
  },
  "files": [
    "dist"
  ],
  "peerDependencies": {
    "@open-wa/plugin-sdk": ">=5.0.0"
  },
  "scripts": {
    "build": "tsc",
    "prepublishOnly": "npm run build"
  }
}

Key Fields

name, Use a scoped name (@myorg/my-plugin) to avoid collisions
main, The entry point for CommonJS consumers
exports, Modern module resolution with ESM support
types, TypeScript type declarations
files, Only ship the dist folder, not source files
peerDependencies, Declare compatibility with @open-wa/plugin-sdk

TypeScript Compilation

Compile your plugin before publishing:

// tsconfig.json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "declaration": true,
    "outDir": "dist",
    "rootDir": "src",
    "strict": true,
    "esModuleInterop": true
  },
  "include": ["src"]
}

Versioning

Semantic Versioning

Follow semver (MAJOR.MINOR.PATCH):

MAJOR, Breaking changes (e.g., removing hooks, changing config schema)
MINOR, New features (e.g., adding new hooks, new config options)
PATCH, Bug fixes

Compatibility with open-wa Versions

Note which versions of open-wa your plugin is compatible with:

{
  "peerDependencies": {
    "@open-wa/plugin-sdk": ">=5.0.0 <6.0.0"
  },
  "engines": {
    "node": ">=22.21.1"
  }
}

Communicating Breaking Changes

When releasing a major version:

Update the README with migration instructions
Use GitHub releases with changelogs
Consider deprecation warnings in the plugin code before removing features

Telling Users How to Load It

Installation

npm install @myorg/my-plugin
# or
pnpm add @myorg/my-plugin

Configuration

Document the exact wa.config.js entries users need:

// wa.config.js
export default {
  plugins: [
    '@myorg/my-plugin',
  ],
  pluginConfig: {
    'my-plugin': {
      // Document each field here
      apiUrl: 'https://api.example.com',
      apiKey: process.env.MY_PLUGIN_API_KEY,
      enabled: true,
    },
  },
};

Documenting Your Plugin

README Template

Your plugin's README should include:

# @myorg/my-plugin

Brief description of what the plugin does.

## Installation

```bash
npm install @myorg/my-plugin
```

## Configuration

Add to your `wa.config.js`:

```js
export default {
  plugins: ['@myorg/my-plugin'],
  pluginConfig: {
    'my-plugin': {
      // required: Description
      apiKey: process.env.MY_PLUGIN_API_KEY,
      // optional: Description (default: value)
      optionName: 'default',
    },
  },
};
```

### Configuration Options

| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| apiKey | string | Yes | - | Your API key |
| optionName | string | No | "default" | Description |

## Features

- Feature 1
- Feature 2

## Troubleshooting

### Common issue 1
Solution...

### Common issue 2
Solution...

Config Options Reference

Document each config field with:

Type
Whether it is required
Default value
Description
Example

Testing Before Publishing

Local Testing with File Path

Before publishing to npm, test locally:

// wa.config.js
export default {
  plugins: [
    './path/to/my-plugin',  // Local file path
  ],
  pluginConfig: {
    'my-plugin': {
      // test config
    },
  },
};

Named Session Testing

Test with a named session to isolate test data:

npx @open-wa/wa-automate --session-id plugin-test --port 8080

Multi-Session Compatibility

If your plugin uses session-specific data, test it with multiple sessions running simultaneously to ensure there are no conflicts.

Plugin getting started, Build your first plugin
Hooks reference, Available hooks
Plugin security model, Security boundaries

Was this helpful?

Wally and his cute companion coffee mug are coding day and night to keep this up-to-date!

Was this helpful?

On this page