ネイティブプラグインを作る

記事を保存したときにログを出すプラグインを作ります。別フォルダーで作り、サイトへ取り込み、設定に登録する流れを説明します。

目次

保存したことをログに残す

このガイドでは、サイト本体と同じ環境で動くネイティブプラグインを作ります。記事を保存すると、サーバーのログに記事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 build

distに出力ができることを確認します。ビルドは、書いたコードを配布・読み込みに使う形へ整える処理です。エラーが出た場合は、サイトへの導入へ進む前に直します。

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です。

公式の参照元

関連ガイド

メニュー
ホーム公式ドキュメント (別タブで開く)

キーワードを入力すると、ガイドの内容から探せます。