#最初のプラグインを作成する

このドキュメントでは、ページで使用できるブロックプラグインをゼロから作成する手順を説明します。NocoBase プラグインの基本的な構造と開発フローを理解するのに役立ちます。

#前提条件

始める前に、NocoBase がインストール済みであることを確認してください。まだインストールしていない場合は、以下を参照してください：

• create-nocobase-app を使用したインストール
• Git ソースからのインストール

インストールが完了したら、開発を始められます。

#ステップ 1：CLI でプラグインスケルトンを作成する

リポジトリのルートディレクトリで以下のコマンドを実行し、空のプラグインを素早く生成します：

yarn pm create @my-project/plugin-hello

コマンドが正常に実行されると、packages/plugins/@my-project/plugin-hello ディレクトリに基本ファイルが生成されます。デフォルトの構造は以下の通りです：

├─ /packages/plugins/@my-project/plugin-hello
  ├─ package.json
  ├─ README.md
  ├─ client-v2.d.ts
  ├─ client-v2.js
  ├─ server.d.ts
  ├─ server.js
  └─ src
     ├─ index.ts                 # デフォルトでサーバーサイドプラグインをエクスポート
     ├─ client-v2                 # クライアントサイドコードの格納場所
     │  ├─ index.tsx             # デフォルトでエクスポートされるクライアントサイドプラグインクラス
     │  ├─ plugin.tsx            # プラグインエントリ（@nocobase/client-v2 Plugin を継承）
     │  ├─ models                # オプション：フロントエンドモデル（フローノードなど）
     │  │  └─ index.ts
     │  └─ utils
     │     ├─ index.ts
     │     └─ useT.ts
     ├─ server                   # サーバーサイドコードの格納場所
     │  ├─ index.ts              # デフォルトでエクスポートされるサーバーサイドプラグインクラス
     │  ├─ plugin.ts             # プラグインエントリ（@nocobase/server Plugin を継承）
     │  ├─ collections           # オプション：サーバーサイドの collections
     │  ├─ migrations            # オプション：データ移行
     │  └─ utils
     │     └─ index.ts
     ├─ utils
     │  ├─ index.ts
     │  └─ tExpr.ts
     └─ locale                   # オプション：多言語
        ├─ en-US.json
        └─ zh-CN.json

作成後、ブラウザで「プラグインマネージャー」ページ（デフォルトアドレス：http://localhost:13000/admin/settings/plugin-manager）にアクセスし、プラグインがリストに表示されているか確認できます。

#ステップ 2：シンプルなクライアントブロックを実装する

次に、プラグインにカスタムブロックモデルを追加し、ウェルカムテキストを表示してみましょう。

1. 新しいブロックモデルファイル client-v2/models/HelloBlockModel.tsx を作成します：

import { BlockModel } from '@nocobase/client-v2';
import React from 'react';
import { tExpr } from '../utils';

export class HelloBlockModel extends BlockModel {
  renderComponent() {
    return (
      <div>
        <h1>Hello, NocoBase!</h1>
        <p>This is a simple block rendered by HelloBlockModel.</p>
      </div>
    );
  }
}

HelloBlockModel.define({
  label: tExpr('Hello block'),
});

2. ブロックモデルを登録します。client-v2/models/index.ts を編集し、新しいモデルをエクスポートして、フロントエンドランタイムでロードできるようにします：

import { ModelConstructor } from '@nocobase/flow-engine';
import { HelloBlockModel } from './HelloBlockModel';

export default {
  HelloBlockModel,
} as Record<string, ModelConstructor>;

コードを保存した後、開発スクリプトを実行している場合は、ターミナル出力にホットリロードのログが表示されるはずです。

#ステップ 3：プラグインをアクティブ化して体験する

コマンドラインまたは管理画面からプラグインを有効にできます：

• コマンドライン

  yarn pm enable @my-project/plugin-hello

• 管理画面：「プラグインマネージャー」にアクセスし、@my-project/plugin-hello を見つけて「アクティブ化」をクリックします。

アクティブ化後、新しい「Modern page (v2)」ページを作成し、ブロックを追加する際に「Hello block」が表示されます。これをページに挿入すると、先ほど作成したウェルカムコンテンツが表示されます。

#プラグインをデフォルトでプリセットまたはデフォルトで有効化する（オプション）

上記では単一プラグインを手動で有効化する方法を説明しました。自分の NocoBase アプリケーションを管理していて、nocobase install（初回インストール）や nocobase upgrade（アップグレード）の実行後に特定のプラグインを自動的に準備しておきたい場合は、2 つの環境変数でプラグインのデフォルト状態を制御できます：

• APPEND_PRESET_LOCAL_PLUGINS（デフォルトプリセットプラグインの追加） — プラグインをプリセット済みのローカルプラグインリストに追加します。インストール後に「プラグインマネージャー」に表示されますが、デフォルトでは無効であり、手動で有効化する必要があります
• APPEND_PRESET_BUILT_IN_PLUGINS（デフォルト内蔵プラグインの追加） — プラグインを内蔵プラグインリストに追加します。インストール時に自動的に有効化され、内蔵プラグインとして「プラグインマネージャー」では無効化も削除もできません

どちらの変数の値もプラグインのパッケージ名（package.json の name）で、複数のプラグインは英語のカンマで区切ります。.env での設定例：

# デフォルトプリセット：プラグインマネージャーのリストに表示されるが、自動的には有効化されない
APPEND_PRESET_LOCAL_PLUGINS=@my-project/plugin-hello,@my-project/plugin-hello-world

# デフォルト有効化：自動的にインストールして有効化され、画面から無効化できない
APPEND_PRESET_BUILT_IN_PLUGINS=@my-project/plugin-hello,@my-project/plugin-hello-world

通常、ローカル開発・デバッグには前述の yarn pm enable で十分です。これら 2 つの変数は「すぐに使える」配布シナリオに適しています——たとえば、固定のプラグインセットを含む NocoBase アプリケーションをパッケージングし、初期化後にプラグインをすぐに利用可能にしたい場合などです。

#ステップ 4：ビルドとパッケージング

プラグインを他の環境に配布する準備ができたら、まずビルドしてからパッケージングする必要があります：

yarn build @my-project/plugin-hello --tar
# または 2 つのステップで実行
yarn build @my-project/plugin-hello
yarn nocobase tar @my-project/plugin-hello

ビルドが完了すると、パッケージファイルはデフォルトで storage/tar/@my-project/plugin-hello.tar.gz に配置されます。

#ステップ 5：他の NocoBase アプリケーションにアップロードする

パッケージファイルをターゲットアプリケーションの ./storage/plugins ディレクトリにアップロードして解凍します。詳細な手順は プラグインのインストールとアップグレード を参照してください。

#関連リンク

• プラグイン開発の概要 — NocoBase マイクロカーネルアーキテクチャとプラグインライフサイクルの理解
• プロジェクトディレクトリ構造 — プロジェクトディレクトリの規約、プラグインのロードパスと優先順位
• サーバーサイド開発の概要 — サーバーサイドプラグインの全体紹介とコア概念
• クライアントサイド開発の概要 — クライアントサイドプラグインの全体紹介とコア概念
• ビルドとパッケージング — プラグインのビルド、パッケージング、配布フロー
• Test テスト — サーバーサイドプラグインのテストケース作成
• create-nocobase-app を使用したインストール — NocoBase のインストール方法の一つ
• Git ソースからのインストール — ソースコードからの NocoBase インストール
• プラグインのインストールとアップグレード — パッケージ済みプラグインを他の環境にアップロード
• 環境変数 — プリセット・内蔵プラグインなどの環境変数設定