Authoring Pulp Engine plugins

Install the public contract and testing helpers:

npm install --save-dev @pulp-engine/plugin-api @pulp-engine/plugin-testing typescript

Your published plugin declares @pulp-engine/plugin-api: ^0.2.0 in peerDependencies; use the same range in development. plugin-testing also uses that peer, so the host, plugin and test helpers share one event-bus instance. The plugin contract follows its own semver line. manifest.pulpEngineVersion checks compatibility with the server, independently of that contract version.

import type { PulpEnginePlugin } from '@pulp-engine/plugin-api'

const plugin: PulpEnginePlugin = {
  manifest: { name: 'pulp-engine-plugin-example', version: '1.0.0', pulpEngineVersion: '>=0.86.0' },
  server(ctx) { ctx.log.info('Example plugin activated') },
}
export default plugin

import type { PulpEnginePlugin } from '@pulp-engine/plugin-api'
import { createTestServerContext } from '@pulp-engine/plugin-testing'

const plugin: PulpEnginePlugin = {
  manifest: { name: 'pulp-engine-plugin-example', version: '1.0.0' },
  server(ctx) { ctx.log.info('Example plugin activated') },
}
const { ctx, registrations } = createTestServerContext()
await plugin.server?.(ctx)
console.log(registrations)

Build an ESM entry point and install the plugin where the server can import it. Set PULP_ENGINE_PLUGINS=pulp-engine-plugin-example (comma-separated for several packages) and restart the server. Configuration is resolved from plugin defaults, configuration files and plugin-prefixed environment variables; see the reference barcode plugin and trust model. Only install plugins you trust: activation runs with the server’s privileges.

The whole plugin-api package, including its loader and registry, is MIT licensed (owner decision, 2026-10-11). This does not change the commercial server licence. The public packages are ESM only. Use Node.js 22.12 or later for plugin development.