Crear un plugin

Empieza con una acción útil. Mantén visibles la compatibilidad, la autoridad y el comportamiento en ejecución a medida que añadas capacidades.

Obtén la plantilla y los tipos

El repositorio público de plugins contiene una plantilla, declaraciones, el registro y comprobaciones de paquetes. Para las API aún no publicadas, compáralo con el contrato actual del código fuente y usa una compilación de desarrollo compatible. La aplicación publicada más reciente puede ser anterior a esta documentación.

Usa Bun para los scripts del repositorio. Copia template/ en plugins/<your-plugin-id>/ y conserva el nombre del directorio igual al ID del manifest.

Un comando mínimo

Este ejemplo registra un comando durante la activación y solo ejecuta su efecto de interfaz cuando el usuario lo ejecuta.

{
  "id": "hello-reader",
  "name": "Hello Reader",
  "version": "0.1.0",
  "schemaVersion": 1,
  "main": "main.js",
  "requires": {
    "contributions": { "commands": "^1.1.0" },
    "services": { "ui": "^1.17.0" }
  }
}

export default {
  activate(ctx) {
    ctx.contributions.commands.register({
      id: "hello",
      title: "Say hello",
      run: () => ctx.services.ui.showToast("Hello, reader!"),
    });
  },
};

Compila el módulo de entrada en un main.js autocontenido. El manifest anterior exige intencionadamente las versiones documentadas actuales; usa rangos anteriores solo después de comprobar y probar esos contratos.

Añade la autoridad útil mínima

Usa el Explorador para encontrar un método y copiar su fragmento inicial de manifest. Un fragmento declara una capacidad; completa los permisos necesarios para la operación concreta.

• Leer datos de la biblioteca requiere library:read; modificarlos requiere library:write.
• Los ajustes usan rutas y operaciones exactas en settingsAccess.
• El HTTP arbitrario necesita service:network y los orígenes permitidos en networkAccess.origins.
• Un método relacionado con el lector dentro de un servicio de interfaz sin permisos adicionales puede necesitar aun así reading:read o reading:write.
• Los permisos de libros se eligen mediante el consentimiento del host y se exponen en ctx.grants.book; un manifest no puede concederse acceso a otro libro.

Inspecciona ctx.capabilities y gestiona los espacios de nombres opcionales ausentes. Conserva los datos propios de ReadAware en sus dominios; el almacenamiento del plugin es para tus propios registros, ajustes y puntos de control.

Trabaja con observaciones y cancelación

Libera los handles cuando ya no los necesites. En las llamadas compatibles, pasa un AbortSignal y espera el resultado real. La cancelación no deshace una escritura ni un efecto remoto que ya haya ocurrido.

Una reacción automática usa ctx.withEvent(delivery) para el trabajo resultante, incluso después de un await. Da un ruleId estable a las suscripciones causales cuando el contrato lo exige. Las acciones iniciadas por el usuario usan el contexto de activación original. Así el host puede detectar bucles sin confundir acciones independientes.

Compila e instala localmente

Sigue los scripts de paquetes del checkout. En el repositorio público de plugins, las comprobaciones normales son:

bun run build
bun run typecheck
bun test
bun run validate

Abre ReadAware → Ajustes → Plugins → Instalar plugin, selecciona la carpeta compilada y revisa el resumen de consentimiento. Prueba la función en la aplicación de escritorio. Vuelve a compilar y reinstalar para comprobar una actualización.

Versiona los datos privados

schemaVersion es independiente de la versión del paquete. Cuando cambie la forma del KV o de los documentos almacenados, proporciona las transiciones de actualización y reducción compatibles mediante migrate(storageCtx, change).

La migración recibe autoridad exclusiva de almacenamiento. Prueba tanto una transición fallida como una correcta: el paquete anterior y los datos confirmados deben seguir siendo utilizables. Evita añadir un cambio de esquema innecesario para actualizaciones ordinarias del código.

Prueba los límites que usa tu función

Comprueba el comportamiento real de Worker/Tauri, los rechazos por permisos y ámbito de libro, la cancelación, la desactivación y reactivación y la recuperación ante fallos. En un plugin de interfaz, incluye navegación con teclado, textos largos y ventanas estrechas. En un plugin que cambia datos, incluye ediciones simultáneas y reinicios cuando la persistencia sea relevante.

Las programaciones se ejecutan mientras la aplicación está abierta; los jobs duraderos solo admiten los planes tipados del host. Ninguno es un proceso general en segundo plano ni un ejecutor de código arbitrario. La referencia de la API describe estos límites.

Publica

Cuando el paquete compilado funcione con los contratos mínimos declarados, sigue la guía de Publicación.