【実務・中級編】Penpotプラグイン自作入門：TypeScriptで独自のアドオン開発をゼロから始める方法 – UI/UX・デザインツール活用バイブル

Penpotプラグイン自作入門：TypeScriptによる独自アドオン開発の極意

デザインツール市場において、オープンソースでありながらFigmaに匹敵するアーキテクチャを持つ「Penpot」は、開発者ファーストなプロダクトチームにとって最強の選択肢となりつつあります。

SVGネイティブなデータ構造、CSS Grid/Flexboxをそのまま取り入れたレイアウトエンジン、そして何よりも「完全にオープンであること」。この強みを最大限に活かすのが、今回解説する「Penpotプラグイン開発」です。

社内のデザインシステムとコードベースを完全に同期させたい、定型的なモックアップ作成の地獄からエンジニアを解放したい――そんなニッチかつ切実な要件を解決するオリジナルプラグインの作り方を、テックリードの視点から実戦形式で伝授します。

—

1. 開発スピードを爆発させる！Penpotショートカット＆環境の極意

プラグイン開発に入る前に、Penpotでの作業効率を極限まで高めるための前提条件を整えます。素手のままでは、プロトタイピングのフィードバックループが遅くなります。

開発体験を劇的に変えるキーボードショートカット

ブラウザベースであるPenpotをIDEのように操るためのマストなショートカットです。

• `Ctrl / Cmd + /`：クイックサーチ（コマンドパレット）。メニューを探す時間をゼロにする。
• `Shift + A`：Auto Layoutの適用（Flexboxのコンテナ化）。
• `Alt + 1` / `Alt + 2`：デザインタブとレイヤーパネルの切り替え。
• `Ctrl + Shift + D`：開発者モード（Inspect）のトグル。生成されるCSSコードを瞬時に確認。

チーム開発の生産性を底上げする「設定共有化ルール」

Penpotを組織導入する際、野良スタイルが乱立するのを防ぐため、リポジトリのルートに以下のガバナンス設定を配置します。

1. カラー・タイポグラフィのトークン化：デザインシステムのリポジトリから、Penpotがインポート可能なJSON形式でトランスパイルするCI/CDパイプラインを構築する。
2. プラグインのモノレポ管理：社内ニッチツールはバラバラに作らず、一つのリポジトリ内でワークスペースとして管理する。

—

2. 開発環境の構築：ゼロからTypeScriptでプラグインを立ち上げる

Penpotのプラグインは、HTML/CSS/TypeScriptで記述されるUIサイド（iframe内）と、Penpotのドキュメントツリーを操作するバックエンドサイド（サンドボックス環境）の2つのコンテキストで構成されています。

プロジェクトの初期化

まずは公式のボイラープレートをベースに、型安全なTypeScript環境を構築します。

mkdir penpot-plugin-custom-token
cd penpot-plugin-custom-token
npm init -y
npm install –save-dev typescript @types/node
npx tsc –init

必須設定ファイル群のベストプラクティス

チーム開発で破綻しないための、実用的な設定ファイルを公開します。

`manifest.json` （プラグインの定義ファイル）

Penpotにプラグインを認識させるためのエントリポイントです。

{
“manifestVersion”: “1.0”,
“name”: “Design Token Sync”,
“id”: “design-token-sync-plugin”,
“version”: “1.0.0”,
“description”: “社内デザイントークンをワンクリックでPenpot上に反映するプラグイン”,
“icon”: “assets/icon.svg”,
“entrypoints”: {
“ui”: “dist/ui.html”,
“plugin”: “dist/plugin.js”
},
“permissions”: [
“read-local”,
“write-local”
]
}

`tsconfig.json` （TypeScriptコンパイラ設定）

ブラウザ環境とサンドボックス環境の両方に対応する厳格な型チェック設定です。

{
“compilerOptions”: {
“target”: “ES2022”,
“module”: “NodeNext”,
“moduleResolution”: “NodeNext”,
“lib”: [“ES2022”, “DOM”],
“strict”: true,
“esModuleInterop”: true,
“skipLibCheck”: true,
“forceConsistentCasingInFileNames”: true,
“outDir”: “./dist”
},
“include”: [“src//”]
}

—

3. 実装：APIを使ったオブジェクト操作とUIパネルの構築

ここでは、「選択したシェイプの色を、社内定義のプライマリカラーに一括変換する」実用的なプラグインを実装します。

① プラグイン・ロジック（`src/plugin.ts`）

Penpotのキャンバス（ドキュメント）を直接操作するサンドボックス側のコードです。

// PenpotプラグインAPIの型定義をインポート（環境に合わせて調整）
import { pluginApi } from “@penpot/plugin-types”;

penpot.ui.onMessage((message) => {
if (message.type === “apply-primary-color”) {
const selectedShapes = penpot.selection;

if (selectedShapes.length === 0) {
penpot.ui.sendMessage({ type: “notify”, text: “シェイプが選択されていません。” });
return;
}

// 社内デザインシステムのプライマリカラー（例: #0A84FF）
const primaryColorHex = “#0A84FF”;

selectedShapes.forEach((shape) => {
// シェイプが塗りをサポートしている場合、色を置換
if (“fillColor” in shape) {
shape.fillColor = primaryColorHex;
}
});

penpot.ui.sendMessage({ type: “notify”, text: `${selectedShapes.length件のオブジェクトを更新しました。` });
}
});

② UIパネル（`src/ui.html`）

ユーザーが操作するコントロールパネルです。モダンなCSS Gridを使用し、Penpotのダークモードにも自然に馴染むデザインにします。

社内トークン同期

選択中の要素にプライマリカラーを適用します。

カラーを同期する

—

4. デバッグとローカルロードの実装手順

コードが書けたら、実際にPenpot上で動作確認を行います。

1. プロジェクトをビルドします。

npx tsc

2. Penpotのブラウザ版、またはセルフホスト環境を開きます。
3. プロジェクトの設定メニュー、またはプラグイン管理画面から「Load Local Plugin（ローカルプラグインの読み込み）」を選択します。
4. 作成したプロジェクトのルートディレクトリ（`manifest.json`が存在する場所）を指定します。
5. プラグインパネルから動作を確認し、コンソールログ（F12キー）でエラーやメッセージの疎通をチェックします。

—

5. テックリードからの提言：プラグイン開発をチームの文化に

Penpotのプラグイン開発は、単なる「ツールのカスタマイズ」ではありません。それは「デザインとコードの言語を統一するアプローチ」です。

今回紹介したような小規模なトークン同期ツールであっても、チームに導入することで「デザイン修正漏れ」「仕様書の解釈違い」といった、開発現場における無駄なコンフリクトを根絶することができます。

オープンソースの自由度を武器に、自分たちのワークフローをハッキングし、プロダクト開発の速度を次の次元へと引き上げましょう。