NarraLeaf Plugins

The official plugin registry for NarraLeaf Studio.

Every plugin listed here is reviewed and published by the NarraLeaf team. Each one lives in its own directory under plugins/, resolves its own dependencies, and is released independently by pushing a git tag. index.json is the generated, machine-readable index a future in-Studio browser will fetch.

简体中文

Install a plugin

1. Download the plugin's .zip from its release and unzip it — you get one folder containing manifest.json.
2. In Studio: Launcher → Plugins → Install from folder, and select that folder.

Full walkthrough: Install a plugin.

Plugins are not sandboxed. A plugin runs with the privileges its manifest declares, and Studio prompts you for them at install time. Read the permissions field before installing anything — including from here.

Write a plugin

Copy the template/ directory to start, then follow the guides on the documentation site:

• Make a plugin — from an empty folder to an installed plugin.
• API reference — the studio and runtime surfaces, method by method.
• Plugin overview — the two entry targets and how the pieces fit.

cp -r template plugins/yourname.your-plugin
cd plugins/yourname.your-plugin
corepack enable
yarn install
yarn build

Validate and package locally before opening a pull request:

node scripts/validate.mjs yourname.your-plugin       # port of Studio's manifest validator
node scripts/generate-index.mjs                      # regenerate index.json
node scripts/package-plugin.mjs yourname.your-plugin # build + zip to .out/

Contributing

Full details in CONTRIBUTING.md. The short version:

1. Branch from develop.
2. Add or change a plugin under plugins/.
3. Run node scripts/generate-index.mjs and commit the result.
4. Open a pull request against develop.

Branch	Purpose
master	Released state. Every release tag is cut from here.
develop	Integration branch. All pull requests target this.

Releases are per-plugin: bump version in manifest.json and package.json, regenerate index.json, merge to master, and push the tag (git tag narraleaf.example@1.0.0). The release workflow refuses to publish if the tag, manifest, and index disagree.

Releasing (maintainers)

Releases are per-plugin and are triggered by pushing a <plugin-id>@<version> tag — nothing else publishes. The release workflow refuses to publish unless the tag, the plugin's manifest.json version, and its index.json entry all agree, so the registry entry must be merged before you tag.

1. Merge the plugin PR into develop. CI runs; nothing is published yet.

2. Merge develop into master — master only advances through release merges, so this is a merge commit (a fast-forward won't apply once master carries release-merge history). Open a PR from develop to master and merge it, or locally:

   git checkout master && git pull
   git merge origin/develop        # creates the release merge commit
   git push origin master

3. Tag on master, then push the tag — the push is what publishes:

   git tag <plugin-id>@<version>          # e.g. narraleaf.example@1.0.0
   git push origin <plugin-id>@<version>  # a local tag alone does nothing

4. Watch it publish: gh run watch --workflow Release. The workflow validates, builds, packages, and attaches <plugin-id>-<version>.zip to a GitHub Release. Its download URL is deterministic — index.json already points at it.

Updating an existing plugin is the same loop: bump version in both manifest.json and package.json, run node scripts/generate-index.mjs, merge, then tag the new <plugin-id>@<version>.

License

The registry tooling is MPL-2.0, matching NarraLeaf Studio. Each plugin declares its own license in its package.json; check the plugin before you depend on it.