signalk-plugin

Author & publish a SignalK plugin

Hard-won notes for building a SignalK Node-server plugin and shipping it to npm. Mirror a clean reference: openwatersio/signalk-tides (TypeScript) is the best one to read for the @signalk/server-api calls.

1. Scaffold

Public repo, npm package, MIT, zero runtime deps where possible. Files: index.js (or TS src/ built with tsc), package.json, LICENSE, README.md, .gitignore (node_modules, *.tgz), tests (index.test.js via node:test, or test/ via vitest), .github/workflows/{test.yml,publish.yml}.

package.json essentials — a missing files ships nothing because .gitignore excludes the build:

{
  "name": "signalk-<name>",
  "type": "module",
  "files": ["index.js"],
  "keywords": ["signalk-node-server-plugin", "signalk-category-utility"],
  "license": "MIT"
}

For a scoped package add "publishConfig": { "access": "public" }. For TypeScript use "files": ["dist"], point "main": "dist/index.js" (and "types": "dist/index.d.ts") at the build output — without main the server resolves a nonexistent root index.js — and add "prepare": "npm run build" so npm publish builds first. The signalk-node-server-plugin keyword is what surfaces it in the SignalK app store.

2. Write new plugins as ESM

Prefer "type": "module" over CJS for anything new. The server has loaded ESM plugins since v2.14.0 (June 2025): it require()s the plugin directory first — Node ≥ 20.19 / ≥ 22.12 loads ESM through require by default — and falls back to dynamic import() resolved via esm-resolve (plain import() can't take a directory path), so ESM plugins load even on Nodes where require(esm) isn't available. (Server 2.30.0 itself requires Node ≥ 22; v2.14.0 required ≥ 20.) The require path unwraps mod.default ?? mod; the import() fallback returns module.default directly — anything without one loads as undefined there. So the entry point must export default function (app) { ... } returning the plugin object. The practical reason to switch: new majors of common dependencies ship ESM-only, and a CJS plugin can only reach those through awkward dynamic import() — an ESM plugin just imports them. For TypeScript, "module": "nodenext" with a default export compiles to the same shape — remember nodenext makes relative imports require explicit .js extensions (./helpers.js, even in .ts files).