第2章 Red Hat Developer Hub のサードパーティープラグイン

前提条件

• @janus-idp/cli パッケージがインストールされている。最新の機能と修正との互換性は、最新バージョン (@latest タグ) を使用してください。
• Node.js と NPM がインストールされ、設定されている。
• サードパーティーのプラグインが、Red Hat Developer Hub のバージョンと互換性がある。詳細は、バージョン互換性マトリックス を参照してください。

• サードパーティーのプラグインには、必要なすべてのメタデータと依存関係を含む有効な package.json ファイルがルートディレクトリーに存在する。

  バックエンドプラグイン

  動的プラグインのサポートとの互換性を確保し、動的プラグインとして使用できるようにするには、既存のバックエンドプラグインに新しい Backstage バックエンドシステムとの互換性が必要です。さらに、これらのプラグインは専用の CLI コマンドを使用して再構築する必要があります。

  新しい Backstage バックエンドシステムエントリーポイント (createBackendPlugin() または createBackendModule() を使用して作成) は、メインパッケージまたは alpha パッケージ (プラグインインスタンスのサポートが alpha API を使用して引き続き提供されている場合) のいずれかからデフォルトのエクスポートとしてエクスポートする必要があります。これにより、プラグインインスタンスの標準プラグイン開発ガイドラインに加えて追加の要件が追加されることはありません。

  動的エクスポートメカニズムはプライベート依存関係を識別し、package.json ファイルの bundleDependencies フィールドを設定します。このエクスポートメカニズムにより、動的プラグインパッケージが自己完結型パッケージとして公開され、そのプライベート依存関係がプライベート node_modules フォルダーにバンドルされることが保証されます。

  特定のプラグイン依存関係では、派生パッケージで特定の処理が必要になります。たとえば、以下のようになります。

  • 共有依存関係 は RHDH アプリケーションにより提供され、動的プラグインパッケージにバンドルされずに、package.json ファイルに peerDependencies としてリストされます。たとえば、デフォルトでは、すべての @backstage スコープパッケージが共有されます。

    --shared-package フラグを使用して、Red Hat Developer Hub アプリケーションにより提供され、動的プラグインパッケージにバンドルされていないことが予想される共有依存関係を指定できます。

    @backstage パッケージをプライベートとして扱うには、否定接頭辞 (!) を使用します。たとえば、プラグインが Red Hat Developer Hub アプリケーションで提供されていない @backstage のパッケージに依存している場合などです。

  • 埋め込まれた依存関係 は、依存関係が最上位レベルに引き上げられた状態で動的プラグインパッケージにバンドルされます。デフォルトでは、-node または -common 接尾辞を持つパッケージが埋め込まれます。

    --embed-package フラグを使用して、追加の埋め込みパッケージを指定できます。たとえば、デフォルトの命名規則に従わない同じワークスペースからのパッケージなどです。

    以下は、共有パッケージと埋め込みパッケージを含む動的プラグインをエクスポートする例です。

    共有パッケージと埋め込みパッケージを使用した動的プラグインのエクスポートの例

    npx @janus-idp/cli@latest export-dynamic-plugin --shared-package '!/@backstage/plugin-notifications/' --embed-package @backstage/plugin-notifications-backend

    Copy to Clipboard Toggle word wrap

    上の例では、以下のようになります。

  • @backstage/plugin-notifications パッケージは、@backstage スコープ内にあるにもかかわらず、プライベート依存関係として扱われ、動的プラグインパッケージにバンドルされます。
  • @backstage/plugin-notifications-backend パッケージは埋め込み依存関係としてマークされ、動的プラグインパッケージにバンドルされています。

  フロントエンドプラグイン

  フロントエンドプラグインは設定に scalprum を使用できます。これは、エクスポートプロセス中に CLI により自動的に生成されます。次のコマンドを実行すると、生成されたデフォルト設定がログに記録されます。

  デフォルト設定をログに記録するコマンドの例

  npx @janus-idp/cli@latest export-dynamic

  Copy to Clipboard Toggle word wrap

  以下はデフォルトの scalprum 設定の例です。

  デフォルトの scalprum 設定

  "scalprum": {
    "name": "<package_name>",  // The Webpack container name matches the NPM package name, with "@" replaced by "." and "/" removed.
    "exposedModules": {
      "PluginRoot": "./src/index.ts"  // The default module name is "PluginRoot" and doesn't need explicit specification in the app-config.yaml file.
    }
  }

  Copy to Clipboard Toggle word wrap

  package.json ファイルに scalprum セクションを追加できます。以下に例を示します。

  scalprum カスタマイズの例

  "scalprum": {
    "name": "custom-package-name",
    "exposedModules": {
      "FooModuleName": "./src/foo.ts",
      "BarModuleName": "./src/bar.ts"
      // Define multiple modules here, with each exposed as a separate entry point in the Webpack container.
    }
  }

  Copy to Clipboard Toggle word wrap

  動的プラグインでは、マウントポイントや動的ルートの静的 JSX など、Developer Hub のニーズに合わせて調整が必要になる場合があります。これらの変更はオプションですが、静的プラグインと互換性がない可能性があります。

  静的 JSX を含めるには、追加のエクスポートを定義し、それを動的プラグインの importName として使用します。以下に例を示します。

  静的および動的プラグインのエクスポートの例

  // For a static plugin
  export const EntityTechdocsContent = () => {...}
  
  // For a dynamic plugin
  export const DynamicEntityTechdocsContent = {
    element: EntityTechdocsContent,
    staticJSXContent: (
      <TechDocsAddons>
        <ReportIssue />
      </TechDocsAddons>
    ),
  };

  Copy to Clipboard Toggle word wrap

手順

• プラグインをエクスポートするには、@janus-idp/cli パッケージの package export-dynamic-plugin コマンドを使用します。

  サードパーティーのプラグインをエクスポートするコマンドの例

  npx @janus-idp/cli@latest package export-dynamic-plugin

  Copy to Clipboard Toggle word wrap

  前のコマンドは、プラグインの JavaScript パッケージ (package.json ファイルを含む) のルートディレクトリーで実行してください。

  結果として得られる派生パッケージは、dist-dynamic サブフォルダーに配置されます。エクスポートされたパッケージ名は、元のプラグイン名の後ろに -dynamic を追加したものです。

  警告

  派生した動的プラグイン JavaScript パッケージは、パブリック NPM レジストリーに公開することはできません。より適切なパッケージオプションは、「サードパーティーのプラグインを動的プラグインとしてパッケージ化して公開する」 を参照してください。NPM レジストリーに公開する必要がある場合は、プライベートレジストリーを使用します。