ネイティブプラグインを作る
記事を保存したときにログを出すプラグインを作ります。別フォルダーで作り、サイトへ取り込み、設定に登録する流れを説明します。
目次
保存したことをログに残す
このガイドでは、サイト本体と同じ環境で動くネイティブプラグインを作ります。記事を保存すると、サーバーのログに記事IDを記録する機能です。ログは、処理が動いたことやエラーを確認する記録です。読者向けの画面に出す文章ではありません。
この例で行う処理自体はサンドボックスでも実現できます。ここではネイティブの登録方法を学ぶために使います。方式の判断は選び方を確認してください。
前提は、Node.js 22.23.4以上、npm、ローカルで動くweekend-noteです。対象はEmDash 1.4.0です。サイトのフォルダーと、これから作るプラグインのフォルダーを行き来します。各手順に書かれた作業場所を確認してください。
1. サイトの隣にプラグインを作る
エディターで、weekend-noteと同じ階層にplugin-activityフォルダーを作り、その中にsrcを作ります。
作業フォルダー/
├── weekend-note/
└── plugin-activity/
└── src/plugin-activity/package.jsonを次の内容で作ります。このパッケージ名は練習用で、公開先の名前を取得したことにはなりません。
{
"name": "@example/plugin-activity",
"version": "0.1.0",
"type": "module",
"main": "./dist/index.mjs",
"exports": {
".": { "types": "./dist/index.d.mts", "import": "./dist/index.mjs" }
},
"files": ["dist"],
"scripts": {
"build": "tsdown src/index.ts --format esm --dts --clean",
"typecheck": "tsc --noEmit"
},
"peerDependencies": { "emdash": "^1.4.0" },
"devDependencies": {
"emdash": "1.4.0",
"tsdown": "^0.20.0",
"typescript": "^5.9.0"
}
}plugin-activity/tsconfig.jsonも作ります。これはTypeScriptの処理方法の設定です。
{
"compilerOptions": {
"target": "ES2022",
"module": "preserve",
"moduleResolution": "bundler",
"strict": true,
"declaration": true,
"outDir": "./dist",
"rootDir": "./src",
"esModuleInterop": true
},
"include": ["src/**/*"],
"exclude": ["node_modules", "dist"]
}2. 登録情報と処理を書く
plugin-activity/src/index.tsに、次を保存します。
import { definePlugin } from "emdash";
import type { PluginDescriptor } from "emdash";
export function activityPlugin(): PluginDescriptor {
return {
id: "plugin-activity",
version: "0.1.0",
format: "native",
entrypoint: "@example/plugin-activity",
};
}
export function createPlugin() {
return definePlugin({
id: "plugin-activity",
version: "0.1.0",
capabilities: ["content:read"],
hooks: {
"content:afterSave": async (event, ctx) => {
ctx.log.info("記事を保存しました", {
collection: event.collection,
contentId: event.content.id,
isNew: event.isNew,
});
},
},
});
}
export default createPlugin;前半のactivityPluginは、設定ファイルから使う登録情報を返します。後半のcreatePluginは、EmDashが動くときに実際の処理を用意します。EmDashはcreatePluginという名前で処理を読み込むため、export function createPlugin()の形を残してください。 export defaultだけにすると、必要な名前で読み込めなくなります。
capabilitiesは使う権限の宣言です。content:afterSaveでは保存内容の情報を受け取るため、content:readが必要です。本文や認証情報を丸ごとログへ出さず、今回は識別子だけ記録します。
3. プラグインを組み立てる
以下のコマンドはVS Codeのターミナルで入力します。Windowsではコマンドプロンプトを選びます。入力画面の開き方
コマンド入力画面をplugin-activityで開き、次を一つずつ実行します。
npm install
npm run typecheck
npm run builddistに出力ができることを確認します。ビルドは、書いたコードを配布・読み込みに使う形へ整える処理です。エラーが出た場合は、サイトへの導入へ進む前に直します。
4. サイトへ登録する
コマンド入力画面でサイトのフォルダーへ移動し、ローカルのプラグインを取り込みます。
VS Codeの File → Open Folder(ファイル → フォルダーを開く)で weekend-note を開き、新しいコマンド入力画面を用意します。Windowsではコマンドプロンプトを使います。
npm install ../plugin-activity../plugin-activity は、サイトと同じ親フォルダーに置いたプラグインの場所です。このnpmへの指定は、MacとWindowsのコマンドプロンプトで同じ書き方を使います。
サイトのastro.config.mjsに次のimportを加えます。
import { activityPlugin } from "@example/plugin-activity";既存のemdash({ ... })の中にpluginsを加えます。すでにある場合は配列へ追記します。
plugins: [activityPlugin()],これは設定の一部分です。データベース、画像保存先、Astroのadapter、Reactの設定など、元からある設定は残してください。ネイティブを入れる先はpluginsで、sandboxedではありません。
5. 保存して確認する
サイトの開発サーバーを再起動し、管理画面で練習記事を保存します。サイト側のコマンド入力画面に「記事を保存しました」と識別子が出ることを確認します。記事の新規作成と編集保存をそれぞれ試してください。
出ない場合は、プラグインのビルド、取り込み先のパス、pluginsへの登録、content:readの宣言、サーバー再起動を順に確認します。プラグインのファイルがサイト側へコピーされる環境では、プラグインを再ビルドした後、サイト側でも再インストールする必要があります。
今回のログは、処理が動いたことを確かめるために使います。後から操作を調べる監査履歴として確実に残す必要があるなら、専用の保存領域を設計します。開発を終えるときはサイトのコマンド入力画面でControl + Cです。