Contents
開発環境の準備とアカウント設定
この章では、Figma プラグイン開発を始めるために最低限必要な「アカウント」「トークン」「ローカル環境」の3点を確認します。作業を順番に済ませておけば、以降の実装フェーズへすぐに移行でき、途中で手戻りが起きにくくなります。
Figma アカウントと Personal Access Token の取得
Figma の Web ダッシュボードから Settings > Personal Access Tokens を開き、Generate new token ボタンを押して名前を入力するとトークンが発行されます。取得した文字列は機密情報ですので、process.env.FIGMA_TOKEN など環境変数で管理し、リポジトリに直接書き込まないようにしてください。
ポイント
- トークンの有効期限や再生成タイミングは公式ドキュメントをご確認ください。
- CI/CD で利用する場合はシークレットストア（GitHub Actions の Secrets 等）に登録すると安全です。
Node.js と npm のインストール手順
- Node.js（現在の LTS バージョン、例: 20.x 系）を公式サイトからダウンロードし、インストーラを実行します。
- ターミナルで
node -vとnpm -vを入力し、バージョンが表示されれば成功です。 - 作業用フォルダーを作成し、
npm init -yでpackage.jsonを生成しておきます。
ヒント：macOS の場合は Homebrew (
brew install node) でも同等にインストールできます。
VS Code 推奨拡張機能
エディタの快適さが生産性を左右します。以下の拡張は「コード品質」「型サポート」「UI デバッグ」の観点で特に有用です。
| 拡張名 | 主な効果 |
|---|---|
| ESLint | コーディング規約違反や潜在的バグをリアルタイムで指摘 |
| Prettier - Code formatter | 保存時に自動整形し、チーム全体のスタイル統一 |
| Figma Plugin API Types（公式） | figma グローバルオブジェクトの TypeScript 型定義を提供 |
| Live Server | ui.html の変更を即座にブラウザでプレビュー |
拡張は VS Code の Marketplace から検索し、インストールボタンをクリックするだけです。設定例として、.vscode/settings.json に以下を追記すると保存時に自動整形が走ります。
|
1 2 3 4 5 |
{ "editor.formatOnSave": true, "eslint.validate": ["typescript", "javascript"] } |
manifest.json の基本構造と注意点
このセクションでは、Figma がプラグインを認識するために必須となる manifest.json の項目を解説し、バージョン管理上の落とし穴を回避するポイントを紹介します。公式ドキュメントは随時更新されるため、「現在」必要なフィールドだけを書き出す形にしています。
必須フィールド一覧（表）
以下の表は「必ず記述が求められる」項目と、簡単な説明・サンプルをまとめたものです。api のバージョン文字列は執筆時点で最新の 1.0.0 ですが、将来変更される可能性がありますので公式リファレンスで都度確認してください。
| フィールド | 説明 | 記述例 |
|---|---|---|
name |
プラグインが UI に表示される名前 | "Hello World" |
id |
Figma が内部的に管理する UUID（自動生成） | "1234abcd-5678‑efgh‑9012‑ijkl3456mnop" |
api |
使用する API のバージョン | "1.0.0" |
main |
Node 環境で実行されるエントリポイント | "src/main.ts" |
ui |
UI 用 HTML ファイルへの相対パス | "src/ui.html" |
manifest_version |
現在は 2 が推奨されますが、将来変更され得ます | 2 |
permissions |
必要な権限リスト（例: ["currentpage"]） |
["currentpage"] |
注意：
manifest_versionを 2 に固定せず「現在は 2 が推奨」と記述することで、将来の変更に柔軟に対応できます。
バージョン管理とプラグイン ID の扱い
- プラグイン ID は一度生成されると書き換えられません。ローカル開発中は
manifest.jsonに記載されたままで問題ありませんが、Community へ公開した後に変更したい場合は新規作成しかできない点に留意してください。 - バージョン番号 は
package.jsonのversionと同様に SemVer（例:0.1.0,0.2.0）で管理すると、リリースノートと合わせて変更履歴が分かりやすくなります。 - manifest_version の更新 は必須ではありませんが、公式が新しいスキーマを導入した際は上げるだけで済むよう設計されています。
TypeScript での開発環境設定
ここからは「初心者でもすぐに書ける」TypeScript 環境構築手順を示します。型定義が揃っていれば、figma. 系 API の利用時にコンパイルエラーでミスを防げます。
プロジェクトの初期化と依存パッケージインストール
ターミナルで以下を実行してください。
|
1 2 3 4 5 6 7 8 9 10 |
# 作業ディレクトリへ移動、npm 初期化（既に実施済みなら省略可） mkdir my-figma-plugin && cd my-figma-plugin npm init -y # TypeScript と Figma 用型定義をインストール npm i -D typescript @figma/plugin-typings # 開発用 CLI（公式推奨）をインストール npm i -D @figma/plugin-helpers |
@figma/plugin-typings が提供する figma.d.ts は自動的に node_modules/@figma/plugin-typings に配置され、TS コンパイラが認識します。
推奨 tsconfig.json 設定
以下の設定は「ESM 形式でビルドしつつ、Figma が期待する CommonJS のインターフェイスも保持」するためのベストプラクティスです。npx tsc --init 後に上書きしてください。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
{ "compilerOptions": { "target": "ES2020", "module": "ESNext", "moduleResolution": "Node", "outDir": "dist", "rootDir": "src", "strict": true, "esModuleInterop": true, "skipLibCheck": true, "forceConsistentCasingInFileNames": true, "typeRoots": ["./node_modules/@types", "./node_modules/@figma/plugin-typings"] }, "include": ["src/**/*.ts"], "exclude": ["node_modules"] } |
ビルドツールの選択と npm スクリプト例
@figma/plugin-helpers が内部で esbuild を呼び出すので、シンプルなスクリプトだけで開発・本番ビルドが完結します。
|
1 2 3 4 5 6 7 |
{ "scripts": { "dev": "npx figma-plugin-helper watch", "build": "npx figma-plugin-helper build" } } |
npm run dev→ ソース変更を検知して自動再ビルド。npm run build→ 最適化・ミニファイされた.zipパッケージがdist/に生成されます。
コード例と UI 実装
この章では、TypeScript で書いた本体 (main.ts) と UI (ui.html) の最小構成を示しながら、型安全にメッセージやレイヤー操作を行う方法を解説します。
main.ts の基本実装（導入文）
以下のコードは「プラグイン起動 → UI 表示 → メッセージ受信 → プラグイン終了」の流れを最小限にまとめたものです。figma.showUI に渡す __html__ はビルド時に自動置換されます。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 |
// src/main.ts /// <reference types="@figma/plugin-typings" /> // UI を 300×150 のサイズで表示 figma.showUI(__html__, { width: 300, height: 150 }); // UI から送られてくるメッセージを型安全に処理 type PluginMessage = | { type: 'close' } | { type: 'run'; payload?: never }; figma.ui.onmessage = (msg: PluginMessage) => { if (msg.type === 'close') figma.closePlugin(); if (msg.type === 'run') applyRedFillToSelection(); }; // 選択レイヤーの塗りを赤に変えるユーティリティ function applyRedFillToSelection() { const nodes = figma.currentPage.selection; for (const node of nodes) { // `fills` が存在するノードだけ対象にする型ガード if ('fills' in node && Array.isArray(node.fills)) { node.fills = [{ type: 'SOLID', color: { r: 1, g: 0, b: 0 } }]; } } // UI 側へ処理結果を通知 figma.ui.postMessage({ type: 'selectionInfo', count: nodes.length, }); } |
ui.html とスタイル（導入文）
ui.html はシンプルなボタンだけの UI とし、Figma が推奨する Inter フォントと公式カラー #0D99FF を使用しています。スクリプトは parent.postMessage でプラグイン側に指示を送ります。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 |
<!-- src/ui.html --> <!DOCTYPE html> <html lang="ja"> <head> <meta charset="UTF-8" /> <style> body { font-family: Inter, sans-serif; margin: 0; padding: 12px; background:#fafafa; } h3 { margin-top:0; font-size:1rem; color:#333; } button { width:100%; padding:8px; border:none; background:#0D99FF; color:#fff; border-radius:4px; cursor:pointer; } button:hover {background:#067ACC;} </style> </head> <body> <h3>選択レイヤーを赤く塗り替える</h3> <button id="run">実行</button> <script> // ボタン押下でプラグインに「run」メッセージを送信 document.getElementById('run').onclick = () => { parent.postMessage({ pluginMessage: { type: 'run' } }, '*'); }; // プラグイン側からの結果通知を受け取って表示 onmessage = (event) => { const msg = event.data.pluginMessage; if (msg?.type === 'selectionInfo') { alert(`選択中のオブジェクトは ${msg.count} 個です`); } }; </script> </body> </html> |
型定義を活用した安全なコード例（導入文）
@figma/plugin-typings が提供する型情報をフルに使うと、次のように「プロパティが存在しない」エラーをコンパイル時に検出できます。
|
1 2 3 4 5 6 7 8 |
// 例：テキストレイヤーかどうかを判定しつつ色変更 function setRedIfPossible(node: SceneNode) { if ('fills' in node && Array.isArray(node.fills)) { // fills が存在すれば安全に代入可能 node.fills = [{ type: 'SOLID', color: { r: 1, g: 0, b: 0 } }]; } } |
ローカルテスト・デバッグ手順
実装が完了したら、Figma デスクトップアプリ上でプラグインを走らせて動作確認します。以下の流れは公式チュートリアルと同様で、エラー発見を最速にするポイントを併記しています。
“Run last plugin” での実行手順（導入文）
npm run dev で自動ビルドが走っている状態で、Figma のメニューから Plugins > Development > Run last plugin を選択すると、最新のコードが即座に反映されます。
- ターミナルで
npm run dev（watch モード）を起動。 - Figma デスクトップアプリ → Plugins > Development > Run last plugin。
- UI が表示されたらボタン操作などを試し、期待通りに動くか確認。
ポイント：コード保存と同時に再ビルドが走るので、変更後は必ず UI をリロード（
Run last plugin再実行）してください。
コンソールデバッグとエラーログの確認方法（導入文）
Figma の開発者ツールは Chrome DevTools と同様に利用でき、console.log や figma.notify が即座に表示されます。
- 起動：
Ctrl+Shift+I（Windows）／⌥⌘I（macOS） - Console タブで
console.log('debug')の出力を確認。 - エラーは赤字でハイライトされ、スタックトレースが付与されるため、
API 権限エラーやmanifest バージョン不一致といった典型的な失敗要因をすぐに特定できます。
|
1 2 3 4 5 6 |
// デバッグ例（main.ts） console.log('Plugin started'); figma.on('selectionchange', () => { console.log('Selection count:', figma.currentPage.selection.length); }); |
ビルド、パッケージング、公開までのフロー
プラグインがローカルで安定したら、Community へ公開できる形にパッケージ化します。ここでは公式 CLI の最新バージョン（執筆時点）を前提とし、手順ごとの注意点も併記しています。
figma-plugin-cli を使ったビルドコマンド（導入文）
@figma/plugin-helpers が内部で esbuild を呼び出すため、シンプルな npm スクリプトだけで完結します。
|
1 2 3 4 5 6 |
# 開発中は watch モードで自動再コンパイル npm run dev # => npx figma-plugin-helper watch # 本番向けに最適化・ミニファイされた zip を作成 npm run build # => npx figma-plugin-helper build |
ビルドが成功すると dist/your-plugin.zip が生成されます。この ZIP には manifest.json、コンパイル済みの JavaScript、そして UI 用 HTML がすべて含まれます。
Community への提出手順とチェックリスト（導入文）
- Figma アプリ → Plugins > Development > Manage Plugins → 「Publish」ボタンをクリック。
- 「Upload zip file」で先ほど作成した
your-plugin.zipを選択。 - タイトル、概要、アイコン、スクリーンショット、利用する権限の説明を入力。
- Submit すると自動レビューが走り、問題なければ数日以内に公開されます。
| 必須項目 | 確認ポイント |
|---|---|
| タイトル・概要 | ユーザーが検索しやすいキーワードを入れる |
| アイコン | 正方形 512 × 512 px、透明背景推奨 |
| スクリーンショット | UI の主要画面を 2 枚以上掲載 |
| 権限説明 | 必要最小限に絞り、何のために使うか明示 |
よくあるエラーと対策（導入文）
実際に公開作業でつまずきやすいケースを表形式でまとめました。エラーメッセージが出たら左列を確認し、右側の対応策を順に試してください。
| エラー | 主な原因 | 推奨対処法 |
|---|---|---|
| API 権限不足 | manifest.json の permissions が足りない |
必要な権限（例: "currentpage"）を追加し、再ビルド |
| CORS エラー | UI から外部 API に直接 fetch している | figma.ui.postMessage → 背景スクリプトで fetch を実行 |
| manifest バージョン不一致 | api フィールドが古い |
公式サイトの「API version」ページで最新文字列を取得し更新 |
| TypeScript コンパイルエラー | 型定義が古い、またはインポートミス | npm i @figma/plugin-typings@latest と tsc --noEmit でチェック |
まとめ
本稿では「アカウント取得」から「TypeScript 環境構築」「コード実装」「ローカルデバッグ」「公開まで」の一連の流れを、最新の公式情報と整合性を保ちつつ具体的に示しました。ポイントは以下の通りです。
- トークンは環境変数で安全管理し、リポジトリに埋め込まない。
manifest.jsonは公式ドキュメントと照らし合わせて必須フィールドだけを書く。バージョン番号は「現在推奨」程度に留め、将来の変更に備える。- TypeScript と型定義を導入すれば、API の誤用がコンパイル時に検出でき、デバッグコストが大幅に削減される。
npm run dev→ Figma の「Run last plugin」での即時テストサイクルを確立し、エラーは開発者ツールで確認する。- ビルドは公式 CLI に任せ、生成された ZIP を Community にアップロードすれば公開完了。
これらの手順に従えば、初心者でも数時間以内に「Hello World」レベルのプラグインを作成し、実際にユーザーへ提供できるようになります。ぜひ手元で試してみてください。