Figma プラグイン開発環境の構築と公開手順 – Node.js・Vite入門

📦 開発環境の準備

1. Node.js と npm（または pnpm / Yarn）をインストール

Tip
プロジェクト規模が大きくなる場合は pnpm や Yarn Berry の導入も検討してください。依存関係のインストールが高速になるうえ、ワークスペース機能で複数プラグインを一元管理できます。

2. 型定義と TypeScript 環境の構築

Figma が公式に提供している型定義 @figma/plugin-typings を使うと、エディタ上で figma.* 系 API の補完が得られます。

tsconfig.json（推奨設定）

ポイント
- typeRoots は ./node_modules/@figma/plugin-typings を指す必要があります。以前の記述 (./node_modules/@figma) では型が解決されません。
- VS Code の標準機能だけで TypeScript の補完は十分に動作します。過去に紹介した「TypeScript Hero」はメンテナンスが停止しており、現在は不要です。

3. ビルドツール：Vite（React/Preact）または esbuild

2024 年以降の Figma プラグインでは Vite がデファクトスタンダードとなっています。軽量かつ高速な HMR が特徴です。

vite.config.ts（React 用サンプル）

package.json にビルドコマンドを追加

npm run dev を実行すると、src/ 配下の変更が自動で dist/ に出力されます。Figma デスクトップアプリはこのフォルダーを参照してプラグインをロードします。

4. コーディング支援ツール（任意）

• ESLint + Prettier：コード品質と整形を自動化
  bash
npm i -D eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin prettier eslint-config-prettier
npx eslint --init # 設定ウィザードに従って TypeScript 用の設定を作成
• Jest + figma-mock：プラグインロジックだけを単体テスト
  bash
npm i -D jest ts-jest @types/jest figma-mock

🗂️ プラグインプロジェクトの構造

1. Figma アプリ内で雛形を作成

2. manifest.json の必須項目

• editorType は必須（Figma、FigJam のいずれか）。
• api はプラグイン API バージョンであり、REST API とは別です。

3. ディレクトリ例

🧩 コアロジックと UI 実装

1. 背景スクリプト src/code.ts

2. UI (src/ui.tsx) – React の例

3. UI 用 HTML (public/index.html)

セキュリティ注記
UI 側で外部スクリプトや eval を使用すると CSP に違反し、Figma がプラグインをブロックします。上記のように最低限のポリシーだけ許可する形が安全です。

4. メッセージングまとめ

🛠️ ビルド・デバッグ・テスト

1. Vite のウォッチモード

• ターミナルに ✓ built in xxx ms と表示され、エラーは赤字で出力されます。
• ビルドが失敗した場合は dist/ が更新されないので、Figma 側のプラグインは古いコードを実行し続けます。

2. Figma デスクトップアプリでデバッグ

1. プラグイン読み込み
2. メニュー > プラグイン > 開発 > 既存のプラグインを読み込む → manifest.json があるフォルダーを指定。
3. 実行
4. 作成したプラグイン名をクリック。
5. コンソール確認
6. Ctrl+Shift+I（macOS は ⌥+⌘+I）でデベロッパーツールを開き、Console タブに figma.notify, console.log, console.error が出力されます。

3. ログとエラーハンドリングのベストプラクティス

4. 単体テスト例（Jest + figma-mock）

src/__tests__/replace-text.test.ts

CI の設定例（GitHub Actions）
yaml
name: CI
on: [push, pull_request]
jobs:
build-test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Setup Node
uses: actions/setup-node@v3
with:
node-version: '20'
- run: npm ci
- run: npm run build
- run: npm test

🚀 公開と運用のベストプラクティス

1. Community へテスト公開する手順

注意：api フィールドはプラグイン API バージョンであり、バージョン番号とは別です。審査の際に混同しないようにしてください。

2. 権限・レートリミット・セキュリティ

最小権限の設定

• manifest.json の permissions は 必要最低限 に絞ります。例としてテキスト置換だけなら "currentpage" があれば十分です。

正しいレートリミット情報（公式ドキュメント参照）

実装例：スロットリング
ts
let lastCall = 0;
const MIN_INTERVAL = 1000; // ms
async function throttledFetch(...args) {
const now = Date.now();
if (now - lastCall < MIN_INTERVAL) await new Promise(r => setTimeout(r, MIN_INTERVAL));
lastCall = Date.now();
return fetch(...args);
}

外部通信の安全策

• fetch の URL は必ず https:// で始める。
• CORS ヘッダーが正しく設定されているか確認（Access-Control-Allow-Origin: * が必要なケースもある）。
• 入力データを直接 HTML に埋め込むと XSS のリスクがあります。React/Preact で JSX を使う場合は自動エスケープが働きますが、 innerHTML は極力避けましょう。

3. 運用・保守のヒント

📌 まとめ

1. 環境構築 – Node + TypeScript + Vite がベストプラクティス。型定義は @figma/plugin-typings を正しいパスで設定。
2. プロジェクト構造 – manifest.json、src/, dist/ の三層構成を守るとビルド・デバッグが楽になる。
3. 実装のコツ – 背景スクリプトと UI の双方向メッセージングは必ず try / catch で囲み、エラーメッセージは figma.notify とコンソールに同時出力。
4. デバッグ・テスト – Vite のウォッチモード＋ Figma デスクトップの DevTools が最速。Jest + figma‑mock でロジック単体テストを自動化。
5. 公開と運用 – 最小権限、正しいレートリミット認識、CSP と XSS 対策は必須。GitHub Actions を活用すれば継続的デプロイが実現できる。

これらの手順に沿って作業すれば、非エンジニアでも 数時間で動くプラグイン が完成し、Community への公開・運用までスムーズに進められます。ぜひ本ガイドをベースに、自分だけの Figma プラグイン開発に挑戦してみてください！ 🚀