セットアップ

必要環境

• Node.js 24+
• pnpm（niyase のリポジトリは pnpm のみを使用します。npm / yarn ではありません）
• 最新のブラウザ（ローカルプレビュー用）

SDK について

@niyase/plugin-sdk は npm に公開済みです（MIT）。ローカルプレビューが使う @niyase/plugin-preview は近日 npm 公開予定です。 niyase 社内で公式プラグインを開発する場合は、モノレポ内（services/turborepo/packages/@niyase/）の pnpm workspace から niyase-plugin CLI をそのまま使えます。

雛形を作る

niyase-plugin new がプラグインプロジェクトを生成します。

pnpm dlx @niyase/plugin-sdk new @your-org/tasks
cd tasks
pnpm install

niyase 社内で公式プラグインを作る場合は、services/turborepo/packages/@niyase/ 配下で niyase-plugin new @niyase/<short-id> を実行します。

生成物:

tasks/
├── package.json        # niyase-plugin スクリプト + SDK devDeps
├── tsconfig.json
└── src/
    ├── manifest.ts     # defineManifest({...})
    ├── Root.tsx        # useNiyase() を使う本体
    └── index.tsx       # createNiyase(); register("@your-org/tasks", Root)

CLI コマンド

コマンド	役割
niyase-plugin new	プラグインの雛形を生成
niyase-plugin build	配布用 IIFE バンドルを生成（dist/bundle.js）
niyase-plugin lint	tsc + validateManifest()（zod）+ 禁止 API 走査
niyase-plugin test	vitest を実行（createTestHost() で MOCK 検証）
niyase-plugin dev	ローカルプレビュー（後述）
niyase-plugin publish	ビルド + 検証 + 申請（公開申請 参照）

register() とローカルプレビュー

エントリファイル（src/index.tsx）は createNiyase() を呼んでからブリッジを初期化し、register(pluginId, Root) でルートコンポーネントをホストに登録します。この 2 行はプラグインの入口であり、本番でもローカルプレビューでも共通です。

pnpm dev          # = niyase-plugin dev
# ▸ http://localhost:4321

niyase-plugin dev は、本物そっくりの汎用シェル（サイドバー相当 / タブ）の中で、あなたのプラグインを <iframe sandbox> + postMessage で実行し、register() が呼ばれると自動でシードされる MOCK バックエンドに接続します（manifest の tables[] からメモリ上にテーブルを再現)。上部の DevBar でテーマ・ロール（executive / employee / customer）・スペース種別・言語（ja / en）・障害注入を切り替えながら確認できます。

プレビューと本番は同じ useNiyase() 契約で動くため（1 インターフェース・2 実装）、ここで見えるものがそのまま本番の見た目になります。

最小プラグイン

// src/Root.tsx
import { useEffect, useState } from "react";
import { useNiyase } from "@niyase/plugin-sdk";

export function Root() {
  const niyase = useNiyase();
  const [items, setItems] = useState<{ id: string; title: string }[]>([]);

  useEffect(() => {
    niyase.data
      .list<{ id: string; title: string }>("task")
      .then((r) => setItems(r.items));
  }, []);

  return (
    <ul>
      {items.map((it) => (
        <li key={it.id}>{it.title}</li>
      ))}
    </ul>
  );
}

次は マニフェスト で manifest.ts の中身を確認します。