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:
- kinotvapp/kino-plugin-watch-party (Party Chat): a player-panel tab with rooms and failover.
- kinotvapp/kino-plugin-news (Solo noticias): a screen and a background job.
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.jsonly 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.jsstraight 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 committedplugin.js, so nobody ships a hand-edited or stale bundle; a test does the same, sonpm testcatches it too. Your other tests load the builtplugin.jswith 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.