1. Preparar el proyecto

Instalar el kit

El kit (@hury/plugin-kit) es un paquete npm con el binario hury-plugin. Se descarga de este portal, con su huella publicada en Descargas:

curl -O https://developer.hury.es/downloads/hury-plugin-kit-0.1.0.tgz
shasum -a 256 hury-plugin-kit-0.1.0.tgz
npm install -g ./hury-plugin-kit-0.1.0.tgz
hury-plugin --version

Compara la salida de shasum con la huella de la página de descargas antes de instalar. hury-plugin necesita Node.js 22 o superior.

Crear el proyecto

hury-plugin init notas --title Notas --author "Mi empresa"
cd notas
npm install

• La clave (notas) debe ser camelCase, de 2 a 40 caracteres y empezar por minúscula. Es estable: no se renombra nunca.
• --title es el nombre visible y --author, el que sale en el Marketplace como «Por …».
• init deja en package.json la dependencia @hury/plugin-kit apuntando a la descarga de este portal. Sin conexión, o para una copia local, usa --kit ./hury-plugin-kit-0.1.0.tgz.

Esto es lo que se ha creado:

notas/
  plugin.json                 ficha: clave, versión, apiVersion, título, categoría
  package.json                scripts (build, typecheck, test) y versiones de fastify, kysely, zod y vue del host
  tsconfig.json               API: tipos del host en node_modules/@hury/plugin-kit/types/host
  api/index.ts                el ZModule: manifiesto, permisos, rutas
  api/routes.ts               rutas Fastify
  api/schemas.ts              esquemas zod de las peticiones
  api/tables.ts               tipos de las tablas propias y los dos casts con el host
  migrations/001_notas.sql    migración idempotente
  admin/index.ts              módulo del panel: ruta y entrada de menú
  admin/pages/NotasPage.vue   la pantalla
  admin/i18n/{en,ca,fr}.json  traducciones
  admin/tsconfig.json         panel: tipos del admin en node_modules/@hury/plugin-kit/types/admin
  test/plugin.test.mjs        pruebas de contrato, migraciones, traducciones y rutas

Comprobar que todo funciona

Antes de tocar nada, ejecuta lo que traen la plantilla y el kit:

npm test
npm run typecheck
npm run build

• npm test ejecuta test/plugin.test.mjs con el runner de Node: comprueba que manifest.key coincide con plugin.json, que los permisos declarados los concede la migración, que las migraciones son idempotentes, que todos los textos del admin están traducidos y las rutas de la API (401 sin sesión, 403 sin permiso, validación, 404). No hace falta base de datos ni el host: el kit compila tu API con el mismo esbuild que hury-plugin build y la carga contra un host de pruebas.
• npm run typecheck ejecuta tsc sobre la API y vue-tsc sobre el panel contra los tipos reales del host, derivados del código de la API y del admin de la demo.
• npm run build genera dist/notas-1.0.0.zip, sin firmar.

Los tres deben terminar sin errores. A partir de aquí, cada paso modifica el proyecto y vuelve a ejecutar la comprobación que toca.

Cómo funciona build

hury-plugin build hace lo mismo que la herramienta interna de Hury, salvo firmar:

1. Compila api/index.ts con esbuild a api/index.mjs. Los import … from "@host/…", kysely, zod y fastify no se empaquetan: se convierten en lecturas de globalThis.__HURY_API__.
2. Compila admin/index.ts con Vite como módulo ESM. Los imports vue, vue-router y @/… se convierten en lecturas de window.__HURY_ADMIN__.
3. Copia migrations/, assets/ y admin/i18n/.
4. Escribe plugin.json (con el bloque admin calculado), checksums.json (sha256 de cada fichero) y el zip.

Falla si tu código importa algo que el host no expone, o si usas import * as del host. Esa lista es el contrato: módulos de la API y módulos del admin.

Siguiente: la API →