Espanso の設定ファイル base.yml を直接編集するのは面倒だったので、ブラウザ上で直感的に管理できる Web アプリ Espanso Manager を作りました。
この記事では、開発に至った経緯と技術的なポイントを紹介します。
Espanso Manager とは
Espanso は、テキスト展開（スニペット）ツールです。:date; と入力すると今日の日付に展開される、といった使い方ができます。
無料で使えるオープンソースのスニペットツール「Espanso」｜導入から使い方
ただ、スニペットが増えてくると YAML ファイルの直接編集 が辛くなってきます。
- 数百件のスニペットから登録したスニペットを検索したいことがある
- GUI上でスニペットを編集・追加・削除したい
Espanso Manager は、これらの問題を解決するために作った GUI ツールです。
作成のきっかけ
aText からの移行で感じた不便さ
以前は Mac で aText を使っていました。
Espanso に移行したとき、機能自体には満足したものの、管理面での不便さ を感じました。
「aText みたいな GUI があれば...」と思い、作ることにしました。
Espanso 自体にも espanso edit コマンドがありますが、結局はテキストエディタが開くだけです。
grep や sed で検索・置換する方法もありますが、日常的なスニペット管理 にはオーバーキル。もっとカジュアルに「あのスニペットどこだっけ？」「ちょっと直したい」ができる環境が欲しかったのです。
主な機能
2ペイン構成のエディタ
左ペインにスニペット一覧、右ペインに編集エリア。aText や Alfred のスニペット管理画面に近い構成です。
検索・ソート・カテゴリフィルタ
- 検索なtrigger と replace の両方を対象に部分一致検索
- ソートなA→Z / Z→A / 元の順序 を切り替え
- カテゴリフィルタなトリガーのプレフィックス（
:,::,<?,<,$など）で自動分類
カテゴリは Espanso の一般的な命名規則に基づいて自動判定されます。例えば :ai; は CSS Property、::bef; は Pseudo Element、<?php は PHP といった具合です。
YAML / CSV のインポート・エクスポート
- YAMLなEspanso の
base.ymlをそのまま読み込み・書き出し可能 - CSVなタブ区切りの独自形式。Excel やスプレッドシートでの一括編集に便利
キーボードショートカット
Cmd + S/Ctrl + S: 保存Tab: テキストエリア内でタブ文字を挿入（フォーカス移動ではなく）
技術的なポイント
技術スタック
React 18 + TypeScript (strict)
Vite（ビルド / 開発サーバー）
Vitest（テストフレームワーク）
lucide-react（アイコン）
状態管理は React hooks のみで完結。小規模なアプリなので、Redux や Zustand は使っていません。
自前の YAML パーサー
最大のこだわりポイント です。
一般的な YAML パーサー（js-yaml など）を使うと、改行コードが正規化 されてしまいます。rn が n に変換されたり、末尾の改行が消えたりする。
Espanso のスニペットでは、置換テキストに 意図的な rn を含めることがあります。Windows 環境向けのテンプレートや、特定のアプリに貼り付ける定型文など。
これを壊さないために、Espanso 固有の YAML 形式に特化した自前パーサー を実装しました。
// リテラルブロック（|）の正確なパース
// rn を含む複数行テキストをそのまま保持
ラウンドトリップテスト（読み込み → 書き出し → 再読み込み）で、元ファイルと完全一致 することを確認しています。
カテゴリ自動判定
トリガーのプレフィックスを見て、14 種類のカテゴリに自動分類します。
const CATEGORY_RULES = [
{ prefix: '::', category: 'Pseudo' },
{ prefix: ':', category: 'CSS Prop' },
{ prefix: '.', category: 'CSS Class' },
{ prefix: '<?wp', category: 'WordPress' },
{ prefix: '<?', category: 'PHP' },
{ prefix: '<', category: 'HTML' },
{ prefix: '___PRE_BLOCK_2___#39;, category: 'JavaScript' },
{ prefix: '%', category: 'Bash' },
{ prefix: '#@', category: 'Markdown' },
{ prefix: '#!', category: 'Python' },
{ prefix: '#', category: 'Shell' },
{ prefix: '&', category: 'Symbol' },
{ prefix: '@', category: 'At-rule' },
];
どのルールにもマッチしない場合は General に分類。自分の使い方に合わせたルールですが、多くの Espanso ユーザーにも使いやすいはずです。
未保存インジケーター
編集中に変更があると「● 未保存」と表示。別のスニペットを選択すると自動保存されるので、保存忘れの心配がありません。
使い方
セットアップ
git clone https://github.com/sarap422/tool-espanso-manager.git
cd tool-espanso-manager
npm install
npm run dev
ブラウザで http://localhost:5173 が開きます。
基本的な流れ
- Import ボタンで
base.ymlを読み込む - 左ペインで検索・フィルタして目的のスニペットを探す
- 右ペインで編集して保存
- .yml ボタンでエクスポート
- エクスポートした
base.ymlを Espanso の設定フォルダ（/Users/user-name/Library/Application Support/espanso/match/base.yml）に配置
今後の予定
- スニペットの重複チェック
- Electron でのデスクトップアプリ化
まとめ
Espanso Manager を使えば、ブラウザ上で aText のように直感的にスニペットを管理できます。特に以下のような方におすすめです。
- スニペットが 100 件を超えている
- 複数行の置換テキストをよく使う
- カテゴリ別に整理したい
試してみてください。
関連記事
無料で使えるオープンソースのスニペットツール「Espanso」｜導入から使い方
