Distribution and registry
ZIPs, GitHub Releases, updates, registry submissions and API types
Release ZIP
A feature package contains its built ESM. The ZIP root must look like:
package.json
dist/index.jsA theme contains package.json, theme.json and optionally its extra CSS. Do not wrap them in a parent folder. The template's pnpm package validates the manifest and creates notyra-plugin.zip, excluding source files and node_modules.
Limits are 20 MiB downloaded, 100 MiB total unpacked and 10,000 entries. Missing root manifests, path traversal, absolute paths and symlinks are rejected. Extract your ZIP and load that folder in Developer Mode to verify functionality and cleanup.
GitHub Releases
pnpm typecheck
pnpm build
pnpm test
pnpm package
git tag v0.1.0
git push origin v0.1.0The template workflow verifies that the tag matches package.json, runs typecheck/build/tests and publishes an asset named exactly notyra-plugin.zip. Tagging and releasing are developer actions. A Release without the ZIP cannot be installed.
A repository can distribute multiple plugins by attaching <Plugin ID>.zip for each one to the same latest Release and listing the same owner/repo in their registry entries. Registry installs and updates prefer the matching ID ZIP, falling back to the legacy notyra-plugin.zip. A mismatched manifest ID aborts the operation. Repository-only installation uses notyra-plugin.zip as its default. Include every plugin in every Release. The official notyra-plugins collection uses this format for ToC and four themes.
Registry submissions
Open a pull request adding a five-string-field entry to registry.json:
{
"id": "my-plugin",
"name": "My Plugin",
"description": "What the plugin does",
"author": "Developer",
"repo": "owner/my-plugin"
}The ID must match the package name inside the ZIP. Keep schemaVersion: 1. Listing does not bypass consent. Explain the source URL, permissions and compatible Notyra range in your README too.
Users check updates from Settings. Incompatible plugins are not loaded. Updates preserve enabled/disabled state and ask again only for added permissions/destinations.
API type package
@notyra/plugin-api is maintained independently and published under npm's @notyra organization. The template and ToC consume it; they contain neither vendored API copies nor its publishing source.
Export the canonical contracts from the app to a checkout of the API repository:
pnpm plugins:export-api ../notyra-plugin-apiExport updates src/ and api-source.json without overwriting package.json, README or workflows. Match the API version/dependencies, then build, test, inspect npm pack and commit generated outputs in the API repository.
The current API version is 3.1.7. Before its first npm publication, consumers pin an immutable repository tarball; after publication, switch them to the exact matching npm version and regenerate lockfiles. Publishing uses GitHub OIDC when a stable GitHub Release is published for a matching version tag on main. However, npm trust prerequisites require the package to already exist on npm; creating a completely new package is a separate bootstrap step before Trusted Publisher configuration.
After creating the package on npm, configure Trusted Publishing with owner yuma-shin, repository notyra-plugin-api, workflow publish.yml, no environment, and direct npm publish allowed. Merge into main, tag that commit, then publish a stable GitHub Release to publish with OIDC/provenance. A tag push alone does not publish. Follow the API repository README.