はじめに·
はじめに
niyase プラグインとは何か、4 つの分類軸、useNiyase() ブリッジの考え方。
niyase プラグインは、スペース単位で有効・無効を切り替えられる機能拡張の仕組みです。 有効化すると、サイドバー（cloud / desktop）またはシェルフ（mobile）に1 つのメニュー項目が追加され、必要ならスペース DB 専用テーブルとダッシュボードカードも増えます。 1 つのプラグインバンドルが、niyase クラウド（Web）・niyase アプリ（Desktop / Mobile）の 3 面で同じように動きます。
プラグインを 4 つの軸で分類する
niyase プラグインは互いに独立した 4 つの軸で分類します。よくある誤解として「公式・認定・独自」を 1 つの選択肢のように並べてしまうケースがありますが、①（誰が作るか）と ②（どう提供するか）は別の軸です。混同しないでください。
| # | 軸 | 値 | 意味 | manifest |
|---|---|---|---|---|
| ① | 開発者 | 公式 / 認定 | niyase が作る（OFFICIAL）／ 外部開発者が作り niyase が審査する（CERTIFIED） | scope |
| ② | 提供範囲・費用 | 標準 / 独自 | 無料で全スペースに公開する（標準）／ エンジニアリング費用をかけて指定スペースだけに提供する（独自） | visibility + plugin_allowed_workspace |
| ③ | 導入可否 | ハイブリッド / クラウド限定 | ローカルスペース・クラウドスペースの両方に導入できる（ハイブリッド、既定）／ クラウドスペースにしか導入できない（クラウド限定） | requiresCloud |
| ④ | 動作パターン | 単独 / PROVIDER-CLIENT | 自スペース内だけで完結する（単独）／ 提供側と受け手側がペアで動き、データを共有する（PROVIDER-CLIENT） | defaultRole + pairedPluginId |
- ① と ② は独立です。独自（有償・指定スペース限定）プラグインも、公式（niyase が受託開発）・認定（外部企業が受託開発）のどちらもあり得ます。
- ④ PROVIDER-CLIENT は必ず ③クラウド限定になります。ローカルスペースには協業相手が存在しえないためです。単独プラグインでも、同期や協業に依存する機能があれば③をクラウド限定にできます。
それぞれの軸の詳しい仕組みは マニフェスト を参照してください。
コア原則 — useNiyase() ブリッジ
プラグインはアプリのソースコードを一切受け取らず、SDK だけで開発します。プラグインが触れる唯一の API 面が useNiyase() ブリッジです。
import { useNiyase } from "@niyase/plugin-sdk";
function Root() {
const niyase = useNiyase();
niyase.data; // 自プラグインの plg_* テーブル CRUD
niyase.core; // コアデータの読み取り（社員・部署・スペース、最小フィールド）
niyase.connections; // PROVIDER-CLIENT 型のみ。WS 跨ぎの接続・共有データ CRUD
niyase.context; // { spaceId, workspaceType, role, audience, locale, theme, plugin } 反応的
niyase.i18n; // プラグイン自前の ja/en メッセージを context.locale で解決
niyase.navigate; // 自プラグイン内のナビ
niyase.toast; // 通知
niyase.palette; // 統合パレット連携
}
1 インターフェース・2 実装:
useNiyase()は、ローカルプレビュー（niyase-plugin dev）では MOCK 実装が、 本番の niyase 上では REAL 実装が注入されます。プラグイン側のコードは同じままで、ローカルで見えるものがそのまま本番の見た目になります。
ブリッジの全面（各名前空間の詳しい API）は UI 統合 と コア API 連携 で扱います。
SDK パッケージ
@niyase/plugin-sdk— npm に公開済み（MIT）。useNiyase()ブリッジ契約、register()、niyase-pluginCLI を含む@niyase/plugin-sdk/manifest—PluginManifest型 +defineManifest()+validateManifest()（zod）@niyase/plugin-sdk/ui— niyase の UI コンポーネント（ビルド時に external 化、実行時はホストの実装が使われる）@niyase/plugin-preview—niyase-plugin devのローカルプレビューシェル。近日 npm 公開予定です（それまでは公式プラグイン開発がモノレポ内で先行利用しています）