Saltar a contenido

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:

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.js solo 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.js directo 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 el plugin.js guardado, para que nadie publique un paquete editado a mano o viejo; una prueba hace lo mismo, así que npm test también lo atrapa. Tus demás pruebas cargan el plugin.js compilado 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.