Backstageプラグイン開発の最適化！フロントエンドとバックエンド間の「コード共有」完璧戦略

7月 2, 2026

—

Backstageプラグインを開発していると、「フロントエンドで使うこのTypeScriptインターフェース、バックエンドでも全く同じものが必要なんだけど、どうしよう？」という悩みに陥ることがあります。

2つのパッケージ間でコードを重複して記述することは、DRY（Don’t Repeat Yourself）原則に反するだけでなく、片方だけを修正したときに発生するランタイムエラーの主犯となることもあります。Backstageメンテナンスチームが推奨する「共通ライブラリパッケージ」アプローチを今すぐ公開します！🛠️

1. 推奨ソリューション：commonパッケージの分離 📦

Backstageアーキテクチャにおいて、フロントエンド(-frontend)とバックエンド(-backend)の両方が参照する必要があるコードがある場合、別途共通パッケージ(Common Package)を作成するのが定石です。

通常、次のような命名規則を使用します：

フロントエンド： plugins/my-plugin
バックエンド： plugins/my-plugin-backend
共通： plugins/my-plugin-common ✨

2. なぜこのようにすべきか？（利点分析）💡

型安全性(Type Safety)： APIリクエスト/レスポンス構造をインターフェースとして定義して共有することで、フロントエンドとバックエンド間のデータ規約が常に一致することを保証できます。
バンドルサイズ最適化： バックエンド専用ライブラリがフロントエンドバンドルに含まれるのを防ぎます。
循環参照防止： フロントエンドがバックエンドを参照したり、その逆の状況が発生しないように、依存関係構造をきれいに保ちます。🛡️

3. 共通パッケージに含めるべき内容 📂

通常、次のようなコードがcommonパッケージの常連です。

APIエンティティおよびインターフェース： サーバーとクライアントがやり取りするJSONデータの形式。
権限定義 (Permissions)： Backstage権限システムで使用する権限オブジェクト。
定数(Constants)： プラグインID、特定のエラーコード、ルーティングパスなど。
汎用ユーティリティ： 日付計算、文字列処理など、環境（Node.js vs Browser）に左右されない純粋関数。

4. 実践！段階別構築ガイド 🛠️

1段階：パッケージ作成

Backstage CLIを使用して新しい共通パッケージを作成するか、既存の構造を模倣してplugins/my-plugin-commonディレクトリを作成します。

2段階：package.json設定

このパッケージは、どこからでもインポートできるように適切な名前とメタデータを持つ必要があります。

3段階：依存関係の追加 (Dependency)

フロントエンドとバックエンドのpackage.jsonに、作成した共通パッケージを追加します。

JSON

// plugins/my-plugin/package.json (フロントエンド)
"dependencies": {
  "@internal/backstage-plugin-my-plugin-common": "workspace:^"
}

// plugins/my-plugin-backend/package.json (バックエンド)
"dependencies": {
  "@internal/backstage-plugin-my-plugin-common": "workspace:^"
}

5. 注意事項：ブラウザとノード間のバランス ⚖️

共通パッケージを作成する際に最も注意すべき点は、「環境中立性」です。

禁止： fs、pathのようなNode.js専用モジュールの使用（フロントエンドでエラー発生）
禁止： window、documentのようなブラウザ専用APIの使用（バックエンドでエラー発生）
推奨： 純粋なTypeScriptコードと、環境に依存しない汎用ライブラリのみを使用してください。

🏁 まとめ

Backstageプラグインの複雑度が高まるほど、commonパッケージの価値は輝きを放ちます。コードの重複を減らし、型安全性を高めるこの戦略は、大規模なプラットフォームチームがBackstageを安定的に運用するための重要な秘訣でもあります。🌟

現在開発中のプラグインがあるなら、今日すぐにcommonパッケージを導入してみてはいかがでしょうか？

タグ： Backstage, PluginDevelopment, CodeSharing, TypeScript, Architecture, Frontend, Backend, SoftwareEngineering