---
title: "Excalidrawの使い方とDockerセルフホスト手順｜Reactへの埋め込みまで"
url: "https://www.issoh.co.jp/tech/details/17487/"
published: 2026-09-08
updated: 2026-09-08
categories: ["開発"]
publisher: "株式会社一創"
---

# Excalidrawの使い方とDockerセルフホスト手順｜Reactへの埋め込みまで

Excalidrawの日本語記事は「ブラウザで開けば手書き風の図が描ける」までで終わっているものがほとんどですが、業務で使うときに引っかかるのはその先です。公式ドキュメントは、自前インスタンスのセルフホストでは共有と共同編集がサポート対象外だと明記しています。この記事では、ブラウザ版の操作からDockerでの自前運用、共同編集を動かすための`excalidraw-room`の併設、`@excalidraw/excalidraw`をReactアプリへ埋め込む最小コード、そしてExcalidraw+を買う場合との損益分岐までを扱います。バージョンと数値は2026年9月8日時点の公式ドキュメントとリポジトリの記載です。描いた図そのものの体裁については[システム構成図とは？種類と書き方・例、発注者が確認すべき観点を解説](https://www.issoh.co.jp/column/details/13136/)で整理しています。

## まとめ｜Excalidrawの採用で最初に決める3項目と費用の目安

先に結論から。決めるのは、①ブラウザ版のまま使うか、②Dockerで自前に置くか、③自社プロダクトへコンポーネントとして埋め込むか、の3つです。

費用の桁も先に示します。Excalidraw+のPlusプランは1ユーザーあたり月6 USD、年払いなら14%引き。10人で使えば月60 USD前後です。一方の自前運用は本体のライセンスがMITなのでソフト費用はゼロですが、共有と共同編集は公式のサポート外に落ちるため、WebSocketサーバを別に立てる工数が乗ります。

バージョンの現在地も押さえておきます。埋め込み用パッケージ`@excalidraw/excalidraw`は0.18.1系、本体リポジトリの最新タグは v0.18.1（2026年4月21日公開）。ライセンスはMIT、GitHubのスターは131,335でした。

## ブラウザ版Excalidrawで1枚の図を描き切るまでの操作と保存形式

まずは入口の確認です。ここは他ツールとの差がほとんど無いので短く済ませ、判断が要る部分に紙幅を回します。

### excalidraw.comを開いてから共有リンクを発行するまでの手順

ブラウザで excalidraw.com を開くと、その場でキャンバスが出ます。アカウント登録もインストールも要りません。図形は矩形・楕円・矢印・直線・フリーハンド・テキスト・画像の7種類で、ツールバーの数字キーがそのままショートカットに割り当たっています。

描いた内容はブラウザのローカルストレージに残るので、タブを閉じても次に開いたときに続きから触れます。他人と同時に触りたいときは、画面右上から共同編集セッションを開始し、発行されたリンクを渡す形。[公式リポジトリのREADME](https://github.com/excalidraw/excalidraw)には、リアルタイム共同編集とエンドツーエンド暗号化がアプリの機能として明記されています。

### .excalidrawとPNG・SVGエクスポートの使い分けの基準

保存形式は3つあり、目的で選びます。再編集する前提のマスターは`.excalidraw`、資料への貼り込みはPNG、印刷や拡大を伴うならSVGです。

`.excalidraw`の中身はJSONです。[公式のJSONスキーマ](https://docs.excalidraw.com/docs/codebase/json-schema)によれば、トップレベルのキーは`type`・`version`・`source`・`elements`・`appState`・`files`の6つで、スキーマの`version`は2です。画像を貼った図では実データが`files`に入るため、ファイルサイズが一気に膨らみます。

```
{
  "type": "excalidraw",
  "version": 2,
  "source": "https://excalidraw.com",
  "elements": [
    {
      "id": "pologsyG-tAraPgiN9xP9b",
      "type": "rectangle",
      "x": 928,
      "y": 319,
      "width": 134,
      "height": 90
    }
  ],
  "appState": { "gridSize": 20, "viewBackgroundColor": "#ffffff" }
}
```

PNGとSVGは見せるための出力です。両方を出しておくと、資料側はPNG、Webへの掲載はSVGと使い分けられます。

## Dockerでセルフホストする手順と5000番ポートでの起動確認

社外SaaSに図を置けない規程がある組織では、自前で立てる選択肢が出てきます。公式が案内している手順はごく短く、詰まるのはコマンドではなく仕様の側です。

### docker composeで開発サーバを3000番に立てる手順

[公式のDevelopmentページ](https://docs.excalidraw.com/docs/introduction/development)に載っている手順は、クローンしてComposeを起動するだけです。

```
git clone https://github.com/excalidraw/excalidraw.git
cd excalidraw
docker-compose up --build -d
```

起動後は`http://localhost:3000`で開きます。[リポジトリのdocker-compose.yml](https://github.com/excalidraw/excalidraw/blob/master/docker-compose.yml)を見ると、ポートは`3000:80`、環境変数は`NODE_ENV=development`で、カレントディレクトリをコンテナへマウントする構成です。ヘルスチェックも無効化されています。開発用の定義であって、そのまま本番へ持っていく形ではありません。

### docker buildと5000番でのrun起動、公式イメージの扱い

本番相当で動かすなら、イメージを組んでからrunします。公式ページに載っている2行です。

```
docker build -t excalidraw/excalidraw .
docker run --rm -dit --name excalidraw -p 5000:80 excalidraw/excalidraw:latest
```

コンテナ内は80番で待ち受け、ホスト側の5000番へ割り当てる形になります。ビルド済みイメージはDocker Hubにも置かれているので、社内レジストリへミラーして配る運用も取れます。中身は静的アセットを配信するだけ。リバースプロキシの背後に置いてTLSを終端させる構成で足ります。

### セルフホスト版のExcalidrawで共有と共同編集が動かない制約

ここが本題です。公式のDevelopmentページには、自前インスタンスのセルフホストは共有や共同編集をサポートしないと書かれています。つまりDockerで立てた瞬間、excalidraw.comで使えていた共同編集セッションのリンク発行が機能しません。

理由は構成にあります。配布されているのはフロントエンドだけで、共同編集の中継を担うWebSocketサーバが同梱されていないためです。1人で描いてファイルを渡す使い方なら困りませんが、複数人で同時に触る前提で自前運用へ移ると、導入後に必ず問題になります。共同編集が要件に入っているなら、次章の構成を組むか、素直に有償版を買う判断になります。

## excalidraw-roomの併設で共同編集を自前運用へ寄せる構成

共同編集の中継サーバは、別リポジトリとして公開されています。ここを併設すれば自前運用でも同時編集は成立しますが、公式のサポート範囲外である点は変わりません。

### excalidraw-roomの起動コマンドと既定ポート3002の確認

[excalidraw-room](https://github.com/excalidraw/excalidraw-room)はSocket.IOで動くコラボレーションサーバです。READMEに載っている起動手順は次の3行で、本番は`pm2 start pm2.production.json`を使います。

```
git clone https://github.com/excalidraw/excalidraw-room.git
cd excalidraw-room
yarn
yarn start:dev
```

待ち受けポートはソースを読むのが確実です。`src/index.ts`では`process.env.PORT`が無い場合、`NODE_ENV`がdevelopmentなら3002、それ以外は80を既定にしています。クロスオリジンの許可は`CORS_ORIGIN`で、既定値は`*`のままなので、社内に閉じる場合でもフロント側のオリジンを明示的に絞ってください。

### VITE\_APP\_WS\_SERVER\_URLで接続先を差し替える設定手順

フロント側は、接続先のWebSocketサーバをビルド時の環境変数で決めます。[excalidraw-appのCollab.tsx](https://github.com/excalidraw/excalidraw/blob/master/excalidraw-app/collab/Collab.tsx)が参照しているのが`VITE_APP_WS_SERVER_URL`です。Viteの規約どおり、`VITE_`接頭辞の変数だけがクライアントへ渡ります。

```
echo "VITE_APP_WS_SERVER_URL=http://localhost:3002" >> .env.development
yarn start
```

本番向けに固めるときは`.env.production`へ同じキーを置いてからイメージをビルドします。ここで注意したいのは、値がビルド時に埋め込まれる点。コンテナ起動時の環境変数では差し替わらないので、ホスト名を変える場合はイメージを作り直すことになります。

## @excalidraw/excalidrawをReactアプリへ埋め込む最小コード

自社の管理画面やドキュメントツールに作図機能を持たせたい、という要件で選ばれるのがこの形です。MITライセンスなので商用製品への組み込みも通ります。

### npm installからExcalidrawを画面に出すまでの最小構成

[公式のインストール手順](https://docs.excalidraw.com/docs/@excalidraw/excalidraw/installation)では、Reactと同時にパッケージを入れます。[npm registry](https://www.npmjs.com/package/@excalidraw/excalidraw)で確認できる最新版は0.18.1、ライセンスはMIT、peerDependenciesはReact 17・18・19のいずれかです。

```
npm install react react-dom @excalidraw/excalidraw
```

描画に必要なコードはこれだけです。

```
import { Excalidraw } from "@excalidraw/excalidraw";

export default function MyApp() {
  return (
    <div style={{ width: "100vw", height: "100vh" }}>
      <Excalidraw />
    </div>
  );
}
```

未リリースの機能を先に試したい場合は`@excalidraw/excalidraw@next`が用意されています。図の初期表示を決めるのは、コンポーネントへ渡す初期データです。この種の組み込みを既存の業務システムへ載せる作業は、画面設計とデータ保存先の設計がセットになるため、[業務用・Webアプリ開発](https://www.issoh.co.jp/service/apps/business/)のように要件定義から入る進め方が向いています。

### Reactへの埋め込みで詰まる親要素の寸法とフォント配信の対処

実装でつまずく箇所は2つに集約されます。1つは寸法。Excalidrawは親要素の幅と高さを100%使う設計のため、親側の寸法がゼロだと何も表示されません。`height: 100vh`のように具体値を持つ要素で囲む必要があります。

もう1つがフォントです。既定ではCDNからフォントを取得します。閉域網や外部通信を禁じた環境ではここで描画が崩れるため、公式手順どおり`node_modules/@excalidraw/excalidraw/dist/prod/fonts`を自前の配信先へコピーし、`window.EXCALIDRAW_ASSET_PATH`にそのパスを設定します。Next.jsのようにサーバ側でレンダリングする構成なら、読み込みをクライアント側に限定してください。

## .excalidrawファイルをGitで版管理するときの差分の見え方

設計図をリポジトリに置く運用は現実的ですが、レビューの扱いには前提が要ります。JSONの中身は座標値の集合なので、テキスト差分としては読めません。

### .excalidrawのJSON差分がレビューに向かない条件と代替策

図形を10ピクセル動かしただけでも`elements`配下の座標が書き換わり、差分は数値の羅列になります。プルリクエストのレビューで「何が変わったか」を読み取るのは無理があるので、変更点は本文で説明する前提に切り替えてください。

運用としては、`.excalidraw`と書き出したPNGを同じディレクトリに並べ、レビューではPNGを見て、編集はマスターの`.excalidraw`で行う形が回ります。画像を貼った図は`files`にBase64のデータが載ってファイルが重くなるため、スクリーンショットの貼り込みは避けて、図の中に文字で書くほうが後々扱いやすくなります。

### Visual Studio Codeの拡張でリポジトリ内の図を直接編集する運用

リポジトリ内の図をブラウザへ持ち出さずに編集したい場合は、Visual Studio Code Marketplaceで配布されている[Excalidraw拡張（pomdtr）](https://marketplace.visualstudio.com/items?itemName=pomdtr.excalidraw-editor)を入れると、`.excalidraw`をエディタ上で開いて描けます。コードとドキュメントを同じウィンドウで往復できるので、実装中の設計メモを図で残す用途に向きます。

この拡張は本家プロジェクトの提供物ではなくコミュニティ製です。社内標準として配る場合は、拡張のバージョン更新に追随できる体制かどうかを先に確認してください。テキストベースの図であれば[VS Codeでシーケンス図・フローチャートを自動生成する手順](https://www.issoh.co.jp/tech/details/2334/)のようにエディタ内で完結する方法もあります。

## Excalidraw+の月6ドルと自前運用のどちらに振るかの判断条件

ここは言い切ります。共同編集が要件に入っているなら、まずExcalidraw+を買ってください。自前運用を選ぶ条件は限定的です。

### Excalidraw+の年額と自前運用のサーバ費を並べた損益分岐

[公式の価格ページ](https://plus.excalidraw.com/pricing)によると、Freeは無期限の無料で、無限キャンバス1シーン・コラボレーター無制限・PNG/SVGの書き出し・ライブラリ・ブラウザ内のエンドツーエンド暗号化まで含みます。Plusは1ユーザー月6 USD、年払いで14%引き、14日間の無料トライアル付きです。

| 項目     | Free    | Plus      |
| ------ | ------- | --------- |
| 費用     | 0 USD   | 月6 USD/人  |
| 年払い割引  | —       | 14%引き     |
| シーン数   | 1つ      | 無制限       |
| クラウド保存 | なし      | あり        |
| 権限管理   | なし      | 編集/閲覧を指定  |
| 書き出し   | PNG・SVG | PDF・PPTXも |
| コメント   | なし      | あり        |

10人のチームなら年払いで年間およそ620 USD。自前運用に置き換えると、フロント配信とWebSocketサーバで小さなVMが2台、TLS証明書の更新、認証の前段（Excalidraw自体はユーザー認証機構を持ちません）、そしてバージョン追随の作業が乗ります。サーバ費だけで年200 USD前後に収まったとしても、月に1時間手を入れれば人件費で逆転します。

### Excalidrawのセルフホストを選ぶべきでない3条件と代替手段

次の3つに1つでも当たるなら、セルフホストは見送ってください。

- 共同編集が必要で、社内に保守担当が固定で置けない
- 誰がどの図を編集したかの監査ログが要件に入っている
- 利用者が10人未満で、外部SaaSの利用を禁じる規程が無い

1つ目は前述のとおり、共同編集がサポート外だからです。2つ目はExcalidrawに認証も監査の仕組みも無いため、要件を満たすには前段のプロキシで独自に作り込むことになります。3つ目は単純に費用対効果が合いません。逆に、図の内容が外部に出せない情報を含み、かつ1人ないし少人数が描いてファイルで配る運用なら、Dockerで立てた静的配信は十分に噛み合います。

## MermaidとExcalidrawの使い分けとAIエージェント連携の入口

作図ツールの選定は、図の見た目ではなく「差分をレビューするか」で決まります。

### 差分レビューが要る図はMermaid、発想段階はExcalidraw

設計書に載せてレビュー対象にする図、つまり変更履歴を追いたい図はテキストで書くべきです。[Mermaid記法はコードブロックとして差分が読める](https://www.issoh.co.jp/tech/details/3374/)ため、プルリクエストのレビューがそのまま成立します。シーケンス図やフローチャートのように構造が決まった図は、この方式が向きます。

一方でExcalidrawが強いのは、構造が決まる前の段階です。要件のヒアリング中にホワイトボード代わりに描く、システムの当たりを付ける、といった自由配置が要る場面。ここをMermaidでやろうとすると記法に思考を合わせる羽目になります。両方を使い、固まった図だけMermaidへ書き直す運用が現実的です。

### Excalidraw MCPでAIに図を描かせるときの前提と使い分け

手で描く以外に、AIエージェント側からキャンバスを操作する道もあります。Model Context Protocol経由でClaude CodeやCursorから図を生成させる構成については、[Excalidraw MCPの導入と使い方](https://www.issoh.co.jp/tech/details/10968/)で実装ごとの違いと設定差分を扱っています。

使い分けの線引きははっきりしています。既存のコードベースから構成図を起こす、といった機械的な作図はMCP側に任せ、人が判断しながら描く図は本体のキャンバスで手を動かす。MCPの各実装は本体とは別のプロジェクトなので、バージョン追随の手間もこの記事で扱った本体とは別に発生します。

## よくある質問

導入検討でよく挙がる5点に、公式ドキュメントとリポジトリの記載をもとに答えます。

### Excalidrawは商用でも無料で使えますか？

本体はMITライセンスで公開されており、商用利用も改変も再配布も認められています。自社製品に`@excalidraw/excalidraw`を組み込んで販売することも可能です。ただしMITの条件として、著作権表示とライセンス条文を配布物に含める必要があります。ホスティング版のExcalidraw+は別で、こちらは1ユーザー月6 USDの有償サービスです。

### 描いた図はどこに保存されますか？

excalidraw.comで描いている間はブラウザのローカルストレージに保持され、明示的に共同編集を始めない限りサーバへは送られません。共同編集セッションではエンドツーエンド暗号化された状態で中継されます。手元に残したい場合は`.excalidraw`として書き出してください。クラウド側に複数のシーンを置いて管理したいなら、Excalidraw+のPlusプランが該当します。

### 社内ネットワークだけで動かせますか？

動きます。`docker build`でイメージを作り、`docker run -p 5000:80`で起動すれば閉域でも図は描けます。ただし公式は自前インスタンスでの共有と共同編集をサポートしないと明記しているため、同時編集が要るなら`excalidraw-room`を別途立て、`VITE_APP_WS_SERVER_URL`で接続先を差し替える構成が必要です。フォントもCDNから取りに行くので、自己ホストの設定を忘れないでください。

### Excalidraw+の無料プランとの違いは何ですか？

Freeでもエディタ機能はフルに使え、コラボレーターの人数制限もありません。差が出るのは保存側です。Freeは無限キャンバス1シーンのみで、Plusになるとシーンとフォルダが無制限になり、クラウド保存・編集と閲覧の権限指定・読み取り専用リンクの埋め込み・コメント・PDFとPPTXの書き出しが加わります。14日間のトライアルがあるので、シーン数の制約が実務で効くかを試してから決められます。

### Reactアプリに組み込むときReact 19でも動きますか？

動きます。npm registryで公開されている0.18.1のpeerDependenciesは、reactとreact-domがともに17.0.2以上・18.2.0以上・19.0.0以上のいずれかを許容する指定です。導入時は親要素に具体的な幅と高さを与えること、外部通信を制限した環境では`window.EXCALIDRAW_ASSET_PATH`でフォントの配信元を自前に向けることの2点を先に押さえてください。

## 関連記事

- [Excalidraw MCPの導入と使い方｜Claude Code・Cursor・Codex設定と実装の選び方](https://www.issoh.co.jp/tech/details/10968/)：AIエージェントからキャンバスを操作する構成。
- [Mermaid記法の使い方を完全ガイド｜無料のLive Editorでフローチャート・シーケンス図を作成](https://www.issoh.co.jp/tech/details/3374/)：差分レビューが要る図をテキストで書く方法。
- [VSCodeでシーケンス図・フローチャート自動生成｜Mermaidが表示されない対処](https://www.issoh.co.jp/tech/details/2334/)：エディタ内で図を完結させる運用。
- [システム構成図とは？種類と書き方・例、発注者が確認すべき観点を解説](https://www.issoh.co.jp/column/details/13136/)：描く図そのものの型と観点。

---

出典: [Excalidrawの使い方とDockerセルフホスト手順｜Reactへの埋め込みまで](<https://www.issoh.co.jp/tech/details/17487/>)（株式会社一創）