LogoNotyra Docs
プラグイン

配布とレジストリ

ZIP・GitHub Releases・更新・レジストリ掲載・API 型パッケージ

配布 ZIP

Feature はビルド済み ESM を含めます。ZIP の直下が次の構造になるようにしてください。

package.json
dist/index.js

Theme は package.json・theme.json と任意の追加 CSS を直下に置きます。親ディレクトリで包まないでください。テンプレートの pnpm package はマニフェストを検証してから notyra-plugin.zip を生成し、ソースや node_modules を除外します。

ダウンロード上限は20 MiB、展開後の合計は100 MiB、エントリ数は10,000です。ルートのマニフェストがない ZIP、パストラバーサル、絶対パス、シンボリックリンクは拒否されます。作成した ZIP を展開したフォルダを開発者モードから読み込み、機能と停止を確認してください。

GitHub Releases

pnpm typecheck
pnpm build
pnpm test
pnpm package
git tag v0.1.0
git push origin v0.1.0

テンプレートのワークフローは package.json とタグのバージョン一致を検査し、型チェック・ビルド・テストに成功すると、正確に notyra-plugin.zip という名前でアセットを公開します。タグとリリースの公開は開発者の操作です。タグ名だけを作って ZIP のない Release を公開してもインストールできません。

同じリポジトリで複数のプラグインを配布する場合は、最新 Release に <Plugin ID>.zip をそれぞれ添付し、レジストリの各エントリに同じ owner/repo を指定します。レジストリからのインストールと更新は ID に一致する ZIP を優先し、なければ従来の notyra-plugin.zip を取得します。マニフェストの ID が要求した ID と異なれば中止します。リポジトリ名だけの直接指定は notyra-plugin.zip を取得するので、これを既定のプラグインにします。毎回の Release に全プラグインを含めてください。公式の notyra-plugins が ToC と4テーマをこの形式で配布します。

レジストリへの掲載

notyra-plugins の registry.json に、次の5項目が文字列のエントリを追加するプルリクエストを送ります。

{
  "id": "my-plugin",
  "name": "My Plugin",
  "description": "What the plugin does",
  "author": "Developer",
  "repo": "owner/my-plugin"
}

id は ZIP 内の package.json の name と一致させます。レジストリの schemaVersion は1のまま維持します。掲載しても同意を省略することはありません。ソース URL、要求する権限、対応する Notyra の範囲を README でも説明してください。

更新はユーザーが設定画面で確認します。互換性がないプラグインは読み込まれません。更新後も有効・無効状態を維持し、新しい Permission・通信先だけ再同意を求めます。

API 型定義パッケージ

@notyra/plugin-api は独立したリポジトリで管理し、npm の @notyra organization から公開します。テンプレートや ToC は利用側であり、API のコピーや公開用パッケージは持ちません。

本体の正本から API リポジトリへソースを同期します。本体側で次を実行してください。

pnpm plugins:export-api ../notyra-plugin-api

生成するのは src/ と api-source.json です。独立リポジトリの package.json・README・workflow は上書きしません。API リポジトリで版・依存を揃え、ビルド・テスト・npm pack を確認して生成物もコミットします。

現在の API 版は3.1.7です。初回公開前は利用側で独立リポジトリの固定コミット tarball を参照し、公開後に完全固定の npm 版へ切り替えてロックファイルを更新します。公開は main にマージ後、バージョンタグに対応する正式な GitHub Release を公開した時点で OIDC を使って行います。ただし npm の仕様上、Trusted Publisher の設定には対象パッケージが既に npm に存在する必要があるため、未作成のパッケージの初回作成は別途事前準備が必要です。

npm 側のパッケージ作成後に Trusted Publisher を owner=yuma-shin、repository=notyra-plugin-api、workflow=publish.yml(環境名は空欄)に設定し、npm publish の直接公開を許可します。その後、main に含まれる API 版のタグで正式な GitHub Release を公開すると、検証後に OIDC/provenance 付きで公開します。タグの push だけでは公開しません。詳細は API リポジトリの README を参照してください。