E EmDash CMS Everything Guides, use cases, plugins, templates
日本語

フックリファレンス

このページ

フックを使うと、プラグインはコンテンツ、メディア、メール、コメント、ページのライフサイクルの特定のポイントで EmDash の動作をインターセプトして変更できます。

フック一覧

フックトリガー変更可能排他的
content:beforeSaveコンテンツ保存前コンテンツデータNo
content:afterSaveコンテンツ保存後なしNo
content:beforeDeleteコンテンツ削除前キャンセル可能No
content:afterDeleteコンテンツ削除後なしNo
media:beforeUploadファイルアップロード前ファイルメタデータNo
media:afterUploadファイルアップロード後なしNo
cronスケジュールタスク実行なしNo
email:beforeSendメール配信前メッセージ、キャンセル可能No
email:deliverトランスポート経由でメール配信なしYes
email:afterSendメール配信成功後なしNo
comment:beforeCreateコメント保存前コメント、キャンセル可能No
comment:moderateコメント承認ステータスの決定ステータスYes
comment:afterCreateコメント保存後なしNo
comment:afterModerate管理者がコメントステータスを変更後なしNo
page:metadataパブリックページの head レンダリングタグの追加No
page:fragmentsパブリックページの body レンダリングスクリプトの挿入No
plugin:installプラグイン初回インストール時なしNo
plugin:activateプラグイン有効化時なしNo
plugin:deactivateプラグイン無効化時なしNo
plugin:uninstallプラグイン削除時なしNo

コンテンツフック

content:beforeSave

コンテンツがデータベースに保存される前に実行されます。コンテンツのバリデーション、変換、エンリッチに使用します。

import { definePlugin } from "emdash";

export default definePlugin({
	id: "my-plugin",
	version: "1.0.0",
	hooks: {
		"content:beforeSave": async (event, ctx) => {
			const { content, collection, isNew } = event;

			if (isNew) {
				content.createdBy = "system";
			}
			content.modifiedAt = new Date().toISOString();

			return content;
		},
	},
});

イベント

interface ContentHookEvent {
	content: Record<string, unknown>; // コンテンツデータ
	collection: string; // コレクションスラッグ
	isNew: boolean; // 作成時は true、更新時は false
}

戻り値

  • 変更されたコンテンツオブジェクトを返して変更を適用
  • void を返して変更なしで通過

content:afterSave

コンテンツ保存後に実行されます。通知、キャッシュ無効化、外部同期などの副作用に使用します。

hooks: {
  "content:afterSave": async (event, ctx) => {
    const { content, collection, isNew } = event;

    if (collection === "posts" && content.status === "published") {
      await ctx.http?.fetch("https://api.example.com/notify", {
        method: "POST",
        body: JSON.stringify({ postId: content.id }),
      });
    }
  },
}

戻り値

戻り値は不要です。

content:beforeDelete

コンテンツ削除前に実行されます。削除のバリデーションや防止に使用します。

hooks: {
  "content:beforeDelete": async (event, ctx) => {
    const { id, collection } = event;

    const item = await ctx.content?.get(collection, id);
    if (item?.data.protected) {
      return false; // 削除をキャンセル
    }

    return true;
  },
}

イベント

interface ContentDeleteEvent {
	id: string; // エントリ ID
	collection: string; // コレクションスラッグ
}

戻り値

  • false を返して削除をキャンセル
  • true または void を返して許可

content:afterDelete

コンテンツ削除後に実行されます。クリーンアップタスクに使用します。

hooks: {
  "content:afterDelete": async (event, ctx) => {
    const { id, collection } = event;

    await ctx.storage.relatedItems.delete(`${collection}:${id}`);
  },
}

メディアフック

media:beforeUpload

ファイルアップロード前に実行されます。ファイルのバリデーション、リネーム、拒否に使用します。

hooks: {
  "media:beforeUpload": async (event, ctx) => {
    const { file } = event;

    if (file.size > 10 * 1024 * 1024) {
      throw new Error("File too large");
    }

    return {
      name: `${Date.now()}-${file.name}`,
      type: file.type,
      size: file.size,
    };
  },
}

イベント

interface MediaUploadEvent {
	file: {
		name: string; // 元のファイル名
		type: string; // MIME タイプ
		size: number; // バイト単位のサイズ
	};
}

戻り値

  • 変更されたファイルメタデータを返して変更を適用
  • void を返して変更なしで通過
  • throw でアップロードを拒否

media:afterUpload

ファイルアップロード後に実行されます。処理、サムネイル、メタデータ抽出に使用します。

hooks: {
  "media:afterUpload": async (event, ctx) => {
    const { media } = event;

    if (media.mimeType.startsWith("image/")) {
      await ctx.kv.set(`media:${media.id}:analyzed`, {
        processedAt: new Date().toISOString(),
      });
    }
  },
}

イベント

interface MediaAfterUploadEvent {
	media: {
		id: string;
		filename: string;
		mimeType: string;
		size: number | null;
		url: string;
		createdAt: string;
	};
}

ライフサイクルフック

plugin:install

プラグインの初回インストール時に実行されます。初期セットアップ、ストレージコレクションの作成、データのシーディングに使用します。

hooks: {
  "plugin:install": async (event, ctx) => {
    await ctx.kv.set("settings:enabled", true);
    await ctx.kv.set("settings:threshold", 100);

    ctx.log.info("Plugin installed successfully");
  },
}

plugin:activate

プラグインが有効化された時（インストール後または再有効化時）に実行されます。

hooks: {
  "plugin:activate": async (event, ctx) => {
    ctx.log.info("Plugin activated");
  },
}

plugin:deactivate

プラグインが無効化された時に実行されます。

hooks: {
  "plugin:deactivate": async (event, ctx) => {
    ctx.log.info("Plugin deactivated");
  },
}

plugin:uninstall

プラグインが削除された時に実行されます。クリーンアップに使用します。

hooks: {
  "plugin:uninstall": async (event, ctx) => {
    const { deleteData } = event;

    if (deleteData) {
      const items = await ctx.kv.list("settings:");
      for (const { key } of items) {
        await ctx.kv.delete(key);
      }
    }

    ctx.log.info("Plugin uninstalled");
  },
}

イベント

interface UninstallEvent {
	deleteData: boolean; // ユーザーがデータ削除を選択
}

Cron フック

cron

スケジュールタスクの実行時に発火します。ctx.cron.schedule() でタスクをスケジュールします。

hooks: {
  "cron": async (event, ctx) => {
    if (event.name === "daily-sync") {
      const data = await ctx.http?.fetch("https://api.example.com/data");
      ctx.log.info("Sync complete");
    }
  },
}

イベント

interface CronEvent {
	name: string;
	data?: Record<string, unknown>;
	scheduledAt: string;
}

メールフック

メールフックはパイプラインを形成します: email:beforeSend → email:deliver → email:afterSend。

email:beforeSend

ケイパビリティ: email:intercept

配信前に実行されるミドルウェアフック。メッセージの変換や配信のキャンセルができます。

hooks: {
  "email:beforeSend": async (event, ctx) => {
    return {
      ...event.message,
      text: event.message.text + "\n\n—Sent from My Site",
    };

    // または false を返して配信をキャンセル
  },
}

イベント

interface EmailBeforeSendEvent {
	message: { to: string; subject: string; text: string; html?: string };
	source: string;
}

戻り値

  • 変更されたメッセージを返して変換
  • false を返して配信をキャンセル
  • void を返して変更なしで通過

email:deliver

ケイパビリティ: email:provide | 排他的: Yes

トランスポートプロバイダー。メールを配信できるプラグインは 1 つだけです。メールサービス経由でメッセージを実際に送信する責任があります。

hooks: {
  "email:deliver": {
    exclusive: true,
    handler: async (event, ctx) => {
      await sendViaSES(event.message);
    },
  },
}

email:afterSend

ケイパビリティ: email:intercept

配信成功後の fire-and-forget フック。エラーはログに記録されますが伝播しません。

hooks: {
  "email:afterSend": async (event, ctx) => {
    await ctx.kv.set(`email:log:${Date.now()}`, {
      to: event.message.to,
      subject: event.message.subject,
    });
  },
}

コメントフック

コメントフックはパイプラインを形成します: comment:beforeCreate → comment:moderate → comment:afterCreate。comment:afterModerate フックは管理者がコメントのステータスを変更した時に別途発火します。

comment:beforeCreate

ケイパビリティ: read:users

コメント保存前のミドルウェアフック。コメントのエンリッチ、バリデーション、拒否ができます。

hooks: {
  "comment:beforeCreate": async (event, ctx) => {
    if (event.comment.body.includes("http")) {
      return false;
    }
  },
}

イベント

interface CommentBeforeCreateEvent {
	comment: {
		collection: string;
		contentId: string;
		parentId: string | null;
		authorName: string;
		authorEmail: string;
		authorUserId: string | null;
		body: string;
		ipHash: string | null;
		userAgent: string | null;
	};
	metadata: Record<string, unknown>;
}

戻り値

  • 変更されたイベントを返して変換
  • false を返して拒否
  • void を返して通過

comment:moderate

ケイパビリティ: read:users | 排他的: Yes

コメントが承認、保留、スパムかを決定します。有効なモデレーションプロバイダーは 1 つだけです。

hooks: {
  "comment:moderate": {
    exclusive: true,
    handler: async (event, ctx) => {
      const score = await checkSpam(event.comment);
      return {
        status: score > 0.8 ? "spam" : score > 0.5 ? "pending" : "approved",
        reason: `Spam score: ${score}`,
      };
    },
  },
}

イベント

interface CommentModerateEvent {
	comment: { /* beforeCreate と同じ */ };
	metadata: Record<string, unknown>;
	collectionSettings: {
		commentsEnabled: boolean;
		commentsModeration: "all" | "first_time" | "none";
		commentsClosedAfterDays: number;
		commentsAutoApproveUsers: boolean;
	};
	priorApprovedCount: number;
}

戻り値

{ status: "approved" | "pending" | "spam"; reason?: string }

comment:afterCreate

ケイパビリティ: read:users

コメント保存後の fire-and-forget フック。通知に使用します。

hooks: {
  "comment:afterCreate": async (event, ctx) => {
    if (event.comment.status === "approved") {
      await ctx.email?.send({
        to: event.contentAuthor?.email,
        subject: `New comment on "${event.content.title}"`,
        text: `${event.comment.authorName} commented: ${event.comment.body}`,
      });
    }
  },
}

comment:afterModerate

ケイパビリティ: read:users

管理者がコメントのステータスを手動で変更した時の fire-and-forget フック。

イベント

interface CommentAfterModerateEvent {
	comment: { id: string; /* ... */ };
	previousStatus: string;
	newStatus: string;
	moderator: { id: string; name: string | null };
}

ページフック

ページフックはパブリックページのレンダリング時に実行されます。プラグインがメタデータやスクリプトを挿入できるようにします。

page:metadata

ケイパビリティ: page:inject

ページの head にメタタグ、Open Graph プロパティ、JSON-LD 構造化データ、リンクタグを追加します。

hooks: {
  "page:metadata": async (event, ctx) => {
    return [
      { kind: "meta", name: "generator", content: "EmDash" },
      { kind: "property", property: "og:site_name", content: event.page.siteName },
      { kind: "jsonld", graph: { "@type": "WebSite", name: event.page.siteName } },
    ];
  },
}

コントリビューションタイプ

type PageMetadataContribution =
	| { kind: "meta"; name: string; content: string; key?: string }
	| { kind: "property"; property: string; content: string; key?: string }
	| { kind: "link"; rel: string; href: string; hreflang?: string; key?: string }
	| { kind: "jsonld"; id?: string; graph: Record<string, unknown> };

key フィールドでコントリビューションの重複排除が行われます — 同じキーを持つ最後のコントリビューションのみが使用されます。

page:fragments

ケイパビリティ: page:inject

ページにスクリプトや HTML を挿入します。信頼された（ネイティブ）プラグインのみ利用可能です。

hooks: {
  "page:fragments": async (event, ctx) => {
    return [
      {
        kind: "external-script",
        placement: "body:end",
        src: "https://analytics.example.com/script.js",
        async: true,
      },
      {
        kind: "inline-script",
        placement: "head",
        code: `window.siteId = "abc123";`,
      },
    ];
  },
}

コントリビューションタイプ

type PageFragmentContribution =
	| {
			kind: "external-script";
			placement: "head" | "body:start" | "body:end";
			src: string;
			async?: boolean;
			defer?: boolean;
			attributes?: Record<string, string>;
			key?: string;
		}
	| {
			kind: "inline-script";
			placement: "head" | "body:start" | "body:end";
			code: string;
			attributes?: Record<string, string>;
			key?: string;
		}
	| {
			kind: "html";
			placement: "head" | "body:start" | "body:end";
			html: string;
			key?: string;
		};

フック設定

フックはハンドラー関数または設定オブジェクトのいずれかを受け付けます:

hooks: {
  // シンプルなハンドラー
  "content:afterSave": async (event, ctx) => { ... },

  // 設定付き
  "content:beforeSave": {
    priority: 50,        // 小さいほど先に実行（デフォルト: 100）
    timeout: 10000,      // 最大実行時間（ミリ秒、デフォルト: 5000）
    dependencies: [],    // これらのプラグインの後に実行
    errorPolicy: "abort", // "continue" または "abort"（デフォルト）
    handler: async (event, ctx) => { ... },
  },
}

設定オプション

オプション型デフォルト説明
prioritynumber100実行順序（小さいほど先）
timeoutnumber5000最大実行時間（ミリ秒）
dependenciesstring[][]先に実行する必要があるプラグイン ID
errorPolicystring"abort"エラーを無視する場合は "continue"
exclusivebooleanfalseemail:deliver、comment:moderate などプロバイダーパターンフック用 — アクティブプロバイダーは 1 つだけ

プラグインコンテキスト

すべてのフックはプラグイン API へのアクセスを持つコンテキストオブジェクトを受け取ります:

interface PluginContext {
	plugin: { id: string; version: string };
	storage: PluginStorage;
	kv: KVAccess;
	content?: ContentAccess;
	media?: MediaAccess;
	http?: HttpAccess;
	log: LogAccess;
	site: { name: string; url: string; locale: string };
	url(path: string): string;
	users?: UserAccess;
	cron?: CronAccess;
	email?: EmailAccess;
}

ケイパビリティ要件とメソッドの詳細はプラグインの概要 — プラグインコンテキストを参照してください。

エラー処理

フック内のエラーは errorPolicy に基づいてログ記録および処理されます:

  • "abort"（デフォルト）— 実行を停止し、該当する場合はトランザクションをロールバック
  • "continue" — エラーをログに記録して次のフックに進む
hooks: {
  "content:beforeSave": {
    errorPolicy: "continue",
    handler: async (event, ctx) => {
      try {
        await ctx.http?.fetch("https://api.example.com/validate");
      } catch (error) {
        ctx.log.warn("Validation service unavailable", error);
      }
    },
  },
}

実行順序

フックは以下の順序で実行されます:

  1. priority で昇順にソート
  2. dependencies を持つプラグインはその依存先の後に実行
  3. 同じ priority 内では、順序は決定的ですが未指定
// 最初に実行（priority 10）
{ priority: 10, handler: ... }

// 2 番目に実行（priority 50）
{ priority: 50, handler: ... }

// 最後に実行（デフォルト priority 100）
{ handler: ... }