Backstageを活性化！TechDocsの完全インストールとYarnワークスペース設定ガイド

6月 27, 2026

—

こんにちは！本日は、Backstageの主要機能の一つであり、開発者体験（DevEx）の華とも呼ばれるTechDocs（テックドックス）のインストール方法について、非常に詳しく解説していきます。🚀

新しいBackstageモノレポを構築した後、「コードとしてのドキュメント（Documentation as Code）」としてTechDocsを追加しようとした際、どのコマンドをどの順序で入力すれば良いか迷ったことはありませんか？Yarnワークスペース環境でフロントエンドとバックエンドのパッケージを完璧にインストールするための「公式ガイド」を公開します！💡

🏗️ TechDocsのインストール、なぜYarnワークスペース方式なのか？

Backstageは基本的にモノレポ（Monorepo）構造を採用しています。フロントエンド（packages/app）とバックエンド（packages/backend）が分離されているため、新しい機能を追加する際には、各パッケージの領域に合ったライブラリをそれぞれインストールする必要があります。

このとき、Yarn Workspaces機能を使用すると、ルートディレクトリから各サブパッケージに移動することなく、簡単にインストールを管理できます。🛠️

🌟 TechDocsインストールにおける「ゴールデンコマンド」の順序

TechDocsを有効にするには、フロントエンド用プラグインとバックエンド用プラグインの両方をインストールする必要があります。

ステップ1：フロントエンドパッケージのインストール (app) 🎨

まず、ユーザーがドキュメントを閲覧できるUI画面を構成するためのパッケージをインストールします。

Bash

yarn workspace app add @backstage/plugin-techdocs

意味: ‘app’というワークスペース（packages/app）にTechDocsフロントエンドライブラリを追加します。

ステップ2：バックエンドパッケージのインストール (backend) ⚙️

次に、ドキュメントデータの処理、生成、提供ロジックを担当するバックエンドパッケージをインストールします。

Bash

yarn workspace backend add @backstage/plugin-techdocs-backend

意味: ‘backend’というワークスペース（packages/backend）にTechDocsバックエンド処理ロジックを追加します。

🔍 インストール後に何をすべきか？（追加設定ガイド）

パッケージをインストールしたからといって、すぐにドキュメントがポンと現れるわけではありません。いくつかのコード連携作業が必要です。🕵️‍♂️

🛠️ フロントエンド接続 (packages/app/src/App.tsx)

インストールした@backstage/plugin-techdocsをアプリのルーティングに登録する必要があります。

TypeScript

// App.tsx内部の例
import { TechdocsPage } from '@backstage/plugin-techdocs';

// ... ルート定義部分
<Route path="/docs" element={<TechdocsPage />} />

🛠️ バックエンド接続 (packages/backend/src/plugins/techdocs.ts)

最新のBackstageバージョンでは、New Backend Systemを使用するケースが多くなっています。この場合、index.tsファイルに以下の1行を追加するだけで十分です。

TypeScript

// packages/backend/src/index.ts
backend.add(import('@backstage/plugin-techdocs-backend/alpha'));

💡 実践ヒント：TechDocsの動作原理を理解する

TechDocsは内部的にMkDocsという静的サイトジェネレーターを使用しています。📖

Preparation: ソースコードリポジトリにあるMarkdownファイルを収集します。
Generation: MkDocsを実行してHTMLに変換します。
Storage: 変換されたHTMLをS3、GCS、またはローカルファイルシステムに保存します。
Visualization: Backstage UI（フロントエンド）がこの保存されたコンテンツを読み込み、ユーザーに表示します。

このプロセスをスムーズに進めるためには、ローカル環境にPythonとmkdocs-techdocs-coreパッケージがインストールされている必要があることを忘れないでください！🐍

🏁 結論：クリーンなインストールがメンテナンスの始まりです！

BackstageモノレポにTechDocsを追加する際は、以下のコマンドを覚えておいてください。

yarn workspace app add @backstage/plugin-techdocs 🎨
yarn workspace backend add @backstage/plugin-techdocs-backend ⚙️

この2つのステップを踏むことで、あなたのチームはコードとドキュメントを一元管理する真のDevOps文化に一歩近づくことになります！🚀