Skip to content

Structure a bigger plugin in files and bundle it

Kino loads exactly one file, your manifest's entry; Splitting your code across files shows the basic idea (write src/, bundle with esbuild). This page is the recipe for a plugin that has grown: a screen, a player-panel tab, a background job, a protocol of its own. It works at any apiVersion.

Two published plugins are built this way and are worth reading whole:

The recipe

  • One responsibility per file, grouped in folders (util/, protocol/, ui/, exports/...), a short comment at the top of each file saying what it owns, and imports that only go one way: no import cycles (a cycle bundles, but it makes the order code runs in depend on who imported whom first).
  • src/plugin.js only re-exports what Kino calls (search, screen, panel, job...) and what your tests use. The bundle keeps exactly those named exports.
  • One shipped file, generated and committed. Kino installs plugin.js straight from your repository and the signature covers its exact bytes, so the generated file is committed, never edited by hand, and signed after every build. Keep it readable (do not minify): people review what they install.
  • Deterministic. The same sources must give the same bytes: no timestamps, no absolute paths (run esbuild from the plugin's folder), one esbuild version ("esbuild": "^0.21.0"). A header line says the file is generated.
  • check:built. A script rebuilds in memory and fails when the result is not exactly the committed plugin.js, so nobody ships a hand-edited or stale bundle; a test does the same, so npm test catches it too. Your other tests load the built plugin.js with the kit, which is what Kino will run.

The build script

The build script both examples use (scripts/build.mjs, esbuild's JS API, so the banner needs no shell quoting):

import * as esbuild from "esbuild";
const result = await esbuild.build({
  absWorkingDir: ROOT, entryPoints: ["src/plugin.js"], outfile: "plugin.js",
  bundle: true, format: "esm", target: "es2020", charset: "utf8",
  banner: { js: "// Generated by `npm run build` from src/. Do not edit this file: edit src/ and rebuild." },
  write: false,
});
const text = result.outputFiles[0].text;   // write it (build), or compare it with plugin.js (--check)
"scripts": {
  "build": "node scripts/build.mjs",
  "check:built": "node scripts/build.mjs --check",
  "test": "node --test test/*.test.mjs",
  "validate": "node sdk/validate.mjs .",
  "sign": "node scripts/sign.mjs"
},
"devDependencies": { "esbuild": "^0.21.0" }

The workflow

Edit src/, npm run build, npm test, raise version (and your changelog), npm run sign, npm run validate, then commit src/ and plugin.js together. Keep node_modules/ in .gitignore. esbuild drops most comments, so the bundle is readable but bare: point people at src/ in your README.

See also Test it locally and Signed plugins.