Estructurar un plugin grande en archivos y empaquetarlo¶
Kino carga exactamente un archivo, el entry de tu manifiesto; Dividir tu código en varios
archivos muestra la idea básica (escribe src/, empaqueta con esbuild). Esta página
es la receta para un plugin que creció: una pantalla, una pestaña del panel del reproductor, un trabajo en segundo plano,
un protocolo propio. Sirve con cualquier apiVersion.
Dos plugins publicados están hechos así y vale la pena leerlos enteros:
- kinotvapp/kino-plugin-watch-party (Party Chat): una pestaña del panel del reproductor con salas y relevo si el anfitrión se va.
- kinotvapp/kino-plugin-news (Solo noticias): una pantalla y un trabajo en segundo plano.
La receta¶
- Una responsabilidad por archivo, agrupados en carpetas (
util/,protocol/,ui/,exports/...), un comentario corto al principio de cada archivo que diga de qué se encarga, e imports que van en un solo sentido: sin ciclos (un ciclo se empaqueta, pero hace que el orden en que corre el código dependa de quién importó a quién primero). src/plugin.jssolo reexporta lo que llama Kino (search,screen,panel,job...) y lo que usan tus pruebas. El paquete conserva exactamente esos exports con nombre.- Un solo archivo publicado, generado y guardado en el repositorio. Kino instala
plugin.jsdirecto de tu repositorio y la firma cubre sus bytes exactos, así que el archivo generado se guarda en git, nunca se edita a mano y se firma después de cada compilación. Déjalo legible (no lo minifiques): la gente revisa lo que instala. - Determinista. Las mismas fuentes tienen que dar los mismos bytes: sin marcas de tiempo, sin rutas absolutas (corre
esbuild desde la carpeta del plugin), una sola versión de esbuild (
"esbuild": "^0.21.0"). Una línea de cabecera dice que el archivo es generado. check:built. Un script vuelve a compilar en memoria y falla si el resultado no es exactamente elplugin.jsguardado, para que nadie publique un paquete editado a mano o viejo; una prueba hace lo mismo, así quenpm testtambién lo atrapa. Tus demás pruebas cargan elplugin.jscompilado con el kit, que es lo que Kino va a correr.
El script de compilación¶
El script que usan los dos ejemplos (scripts/build.mjs, con la API de JS de esbuild, así el banner no necesita
comillas de shell):
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" }
El flujo de trabajo¶
Edita src/, npm run build, npm test, sube version (y tu registro de cambios), npm run sign, npm run validate,
y luego guarda src/ y plugin.js juntos en el mismo commit. Deja node_modules/ en .gitignore. esbuild quita la
mayoría de los comentarios, así que el paquete es legible pero escueto: en tu README, manda a la gente a src/.
Mira también Probar en local y Plugins firmados.