フックリファレンス | EmDash CMS Everything

フックにより、プラグインはコンテンツ・メディア・メール・コメント・ページのライフサイクル上の特定のポイントで EmDash の動作を横取りして変更できます。

フックの概要

次の表は各フック、そのトリガー、変更可能な内容、排他性を示します。

Hook	トリガー	変更可能	排他
`content:beforeSave`	コンテンツ保存前	コンテンツデータ	いいえ
`content:afterSave`	コンテンツ保存後	なし	いいえ
`content:beforeDelete`	コンテンツ削除前	キャンセル可能	いいえ
`content:afterDelete`	コンテンツ削除後	なし	いいえ
`content:beforePublish`	コンテンツ公開前	キャンセル可能	いいえ
`content:beforeSchedule`	コンテンツ予約公開前	キャンセル可能	いいえ
`content:beforeUnpublish`	コンテンツ非公開前	キャンセル可能	いいえ
`content:afterPublish`	コンテンツ公開後	なし	いいえ
`content:afterUnpublish`	コンテンツ非公開後	なし	いいえ
`content:afterRestore`	コンテンツ復元後	なし	いいえ
`content:afterSchedule`	コンテンツ予約公開後	なし	いいえ
`content:afterUnschedule`	コンテンツ予約解除後	なし	いいえ
`media:beforeUpload`	ファイルアップロード前	ファイルメタデータ	いいえ
`media:afterUpload`	ファイルアップロード後	なし	いいえ
`cron`	スケジュールされたタスク実行	なし	いいえ
`email:beforeSend`	メール配信前	メッセージ、キャンセル可能	いいえ
`email:deliver`	トランスポート経由でメール配信	なし	はい
`email:afterSend`	メール配信成功後	なし	いいえ
`comment:beforeCreate`	コメント保存前	コメント、キャンセル可能	いいえ
`comment:moderate`	コメント承認状態の決定	ステータス	はい
`comment:afterCreate`	コメント保存後	なし	いいえ
`comment:afterModerate`	管理者がコメントステータスを変更した後	なし	いいえ
`page:metadata`	公開ページの head をレンダリング	タグの追加	いいえ
`page:fragments`	公開ページの body をレンダリング	スクリプトの注入	いいえ
`plugin:install`	プラグイン初回インストール時	なし	いいえ
`plugin:activate`	プラグイン有効化時	なし	いいえ
`plugin:deactivate`	プラグイン無効化時	なし	いいえ
`plugin:uninstall`	プラグイン削除時	なし	いいえ

コンテンツフック

`content:beforeSave`

Capability: content:write

コンテンツがデータベースに保存される前に実行されます。検証、変換、コンテンツの付加情報追加に使います。サンドボックス内のフックは、バージョン 1 のフック結果で SAVE_REJECTED エラーと 1〜500 文字のプレーンテキスト reason を返すことで保存を拒否します。API は SAVE_REJECTED で応答し、管理画面はプラグインを特定して理由をテキスト表示します。空、長すぎる、不正、未知のエラー結果は、汎用の CONTENT_HOOK_ERROR 応答で保存に失敗します。

ホストプロセスからは、emdash からエクスポートされる ContentSaveRejectedError を throw して保存を拒否できます。いずれの実行モードからのその他の例外も、例外メッセージを公開しない汎用応答で保存に失敗します。

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;

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

			// Return modified content
			return content;
		},
	},
});

イベント

interface ActorInfo {
	readonly id: string;
	readonly role: number;
}

interface ContentHookEvent {
	content: Record<string, unknown>; // Content data
	collection: string; // Collection slug
	isNew: boolean; // True for creates, false for updates
	id?: string; // ID of the existing item on updates; absent on creates
	actor?: ActorInfo; // Authenticated user that initiated the save
}

更新時、content には送信されたフィールド値のみが含まれます。フックが保存済みエントリと比較する必要がある場合は、ctx.content.get(event.collection, event.id) で読み込みます。認証済み REST、ビジュアル編集、MCP による保存には actor が含まれます。認証ユーザーなしの内部書き込みでは省略されます。

戻り値

変更を適用するには、変更後のコンテンツオブジェクトを返す
上限付きプレーンテキスト理由で保存を拒否するには、サンドボックスフックのエラーエンベロープを返す
変更なしで通過させるには void を返す

サンドボックス内のフックが保存を拒否する場合は、次の完全なエンベロープを返します。

return {
	__emdashSandboxHookResult: true,
	version: 1,
	error: {
		code: "SAVE_REJECTED",
		reason: "Add a summary before saving.",
	},
};

ホストは reason を trim し、1〜500 文字を受け付けます。

`content:afterSave`

Capability: content:read

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

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

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

イベント

content:afterSave は content、collection、isNew、および任意の認証済み actor を受け取ります。content は保存済みの完全なエントリで、データベース ID は content.id、コレクションのフィールドは content.data 配下にあります。content:beforeSave の更新で使う別の任意 id は、保存後には存在しません。

戻り値

戻り値は不要です。

`content:beforeDelete`

Capability: content:read

コンテンツ削除前に実行されます。削除の検証や防止に使います。

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

    // Prevent deletion of protected content
    const item = await ctx.content?.get(collection, id);
    if (item?.data.protected) {
      return false; // Cancel deletion
    }

    // Allow deletion
    return true;
  },
}

イベント

interface ContentDeleteEvent {
	id: string; // Entry ID
	collection: string; // Collection slug
	permanent?: false; // Present for native plugins; omitted in the sandbox runtime
}

content:beforeDelete は、エントリがゴミ箱に移動するときのみ実行されます。ネイティブプラグインは permanent: false を受け取ります。サンドボックスランタイムは id と collection のみ送ります。サンドボックス内のフックではこのフィールドで分岐しないでください。完全削除は content:beforeDelete をバイパスするため、フックは管理者がゴミ箱内のエントリを完全削除するのを防げません。

戻り値

削除をキャンセルするには false を返す
許可するには true または void を返す

`content:afterDelete`

Capability: content:read

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

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

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

イベントには id、collection、permanent が含まれます。permanent はゴミ箱へ移動するとき false、完全削除のとき true です。ゴミ箱から復元したエントリがまだ必要とするデータを削除する前に確認してください。このフックに戻り値はありません。

`content:beforePublish`

Capability: hooks.content-policy:register

コンテンツ公開前に実行されます。公開を許可するには void を、拒否するには { cancel: true, reason } を返します。EmDash は reason に 1〜500 文字のプレーンテキストを受け付け、明示的キャンセルでは PUBLISH_REJECTED を返します。

イベントには現在の content、collection、origin が含まれます。認証済み API、MCP、ビジュアルエディターの操作には、対応する source を伴う actor も含まれます。visual-editor origin には、認証済みツールバーレンダーからの署名付き短期 action トークンが必要です。予約公開エントリは期限到来時にこのフックを再実行します。スケジューラによる拒否は予約を解除し、ダッシュボードに対象エントリと理由を表示します。予約・公開・削除が成功すると記録は消えます。管理者は古い記録を解除できます。

`content:beforeSchedule`

Capability: hooks.content-policy:register

エントリに公開日時が設定される前に実行されます。content:beforePublish と同じ判定エンベロープと origin フィールドを使い、イベントに scheduledAt を追加します。明示的キャンセルでは SCHEDULE_REJECTED を返します。

content:beforeUnschedule フックはありません。管理者は将来の公開をいつでもキャンセルできます。

`content:beforeUnpublish`

Capability: hooks.content-policy:register

公開中のコンテンツを非公開にする前に実行されます。content:beforePublish と同じ判定エンベロープと origin フィールドを使い、明示的キャンセルでは UNPUBLISH_REJECTED を返します。

hooks.content-policy:register は content:read、content:write、公開操作を暗黙的に付与しません。無効な判定と予期しない abort ポリシーエラーは、例外メッセージを公開せず安全側に閉じます（fail-closed）。

`content:afterPublish`

エントリの公開成功後（予約時刻に EmDash が自動公開した場合を含む）に実行されます。公開済みエントリに依存する処理（外部サービスへの通知、外部検索インデックスの更新など）に使います。

hooks: {
  "content:afterPublish": async (event, ctx) => {
    ctx.log.info(`Published ${event.collection}/${event.content.id}`);
  },
}

このフックには content:read capability が必要です。EmDash は公開応答の後に実行するため、戻り値でエントリを変更したり公開を取り消したりできません。エラーはログに記録されます。errorPolicy: "abort" の場合、後続の publish フックは実行されません。

`content:afterUnpublish`

エントリの非公開成功後に実行されます。外部システムが保持するコンテンツのコピーを削除・更新するのに使います。非公開は保留中の予約もキャンセルしますが、content:afterUnschedule は実行しません。

hooks: {
  "content:afterUnpublish": async (event, ctx) => {
    ctx.log.info(`Unpublished ${event.collection}/${event.content.id}`);
  },
}

このフックは content:afterPublish と同じ content:read 要件、遅延実行、イベント形状、戻り値なしの契約を持ちます。

`content:afterRestore`

ゴミ箱からコンテンツが復元された後に実行されます。content:read capability が必要です。復元されたエントリは下書きで予約はありません（ゴミ箱に移したときのステータスに関わりません）。予約の解除だけでは content:afterUnschedule は実行されません。

hooks: {
  "content:afterRestore": async (event, ctx) => {
    ctx.log.info(`Restored ${event.collection}/${event.content.id}`);
  },
}

`content:afterSchedule`

将来公開のためにコンテンツが予約された後に実行されます。content:read capability が必要です。

hooks: {
  "content:afterSchedule": async (event, ctx) => {
    ctx.log.info(`Scheduled ${event.collection}/${event.content.id}`);
  },
}

`content:afterUnschedule`

予約公開が解除された後に実行されます。content:read capability が必要です。

hooks: {
  "content:afterUnschedule": async (event, ctx) => {
    ctx.log.info(`Unscheduled ${event.collection}/${event.content.id}`);
  },
}

イベント

interface ContentStateChangeEvent {
	content: Record<string, unknown>;
	collection: string;
}

このイベント形状は content:afterPublish、content:afterUnpublish、content:afterRestore、content:afterSchedule、content:afterUnschedule で共有されます。content は状態変更後の完全なエントリで、id、slug、ステータスを含みます。コレクションのフィールドは content.data 配下にあります。

戻り値

戻り値は不要です。

メディアフック

`media:beforeUpload`

Capability: media:write

ファイルアップロード前に実行されます。検証、リネーム、拒否に使います。

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

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

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

イベント

interface MediaUploadEvent {
	file: {
		name: string; // Original filename
		type: string; // MIME type
		size: number; // Size in bytes
	};
}

戻り値

変更を適用するには、変更後のファイルメタデータを返す
変更なしで通過させるには void を返す
アップロードを拒否するには throw する

`media:afterUpload`

Capability: media:read

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

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

    if (media.mimeType.startsWith("image/")) {
      // Store image metadata
      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;
	};
}

戻り値

戻り値は不要です。

ライフサイクルフック

ライフサイクルフックには登録用 capability は不要です。

`plugin:install`

プラグインが初めてインストールされたときに実行されます。初期セットアップ、ストレージコレクション作成、シードデータに使います。

hooks: {
  "plugin:install": async (event, ctx) => {
    // Initialize default settings
    await ctx.settings.set("enabled", true);
    await ctx.settings.set("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:install、plugin:activate、plugin:deactivate は空のイベントオブジェクトを受け取り、戻り値はありません。

`plugin:uninstall`

プラグインが削除されたときに実行されます。クリーンアップに使います。

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

    if (deleteData) {
      // Clean up all plugin data
      const items = await ctx.settings.list();
      for (const { key } of items) {
        await ctx.kv.delete(key);
      }
    }

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

イベント

interface UninstallEvent {
	deleteData: boolean; // User chose to delete data
}

アンインストールフックに戻り値はありません。

Cron フック

`cron`

Capability: 不要

スケジュールされたタスクが実行されたときに発火します。タスクは ctx.cron.schedule() でスケジュールします。Cron 式は各ホストで UTC として評価されます。

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;
}

Cron フックに戻り値はありません。

メールフック

プラグインが送信するメッセージでは、メールフックは email:beforeSend → email:deliver → email:afterSend の順で実行されます。システムの認証メッセージは email:deliver に直接進み、email:beforeSend と email:afterSend は実行されません。

`email:beforeSend`

Capability: hooks.email-events:register

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

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

    // Or return false to cancel delivery
  },
}

イベント

interface EmailBeforeSendEvent {
	message: {
		to: string;
		cc?: string[];
		replyTo?: string;
		subject: string;
		text: string;
		html?: string;
	};
	source: string;
}

戻り値

変換するには変更後のメッセージを返す
配信をキャンセルするには false を返す

`email:deliver`

Capability: hooks.email-transport:register | 排他: はい

トランスポートプロバイダーです。メールを配信できるプラグインは 1 つのみです。メールサービス経由で実際に送信する責任を持ちます。

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

イベントと戻り値

interface EmailDeliverEvent {
	message: {
		to: string;
		cc?: string[];
		replyTo?: string;
		subject: string;
		text: string;
		html?: string;
	};
	source: string;
}

フックに戻り値はありません。source は EmDash 認証メッセージでは "system"、プラグイン送信メッセージではプラグイン ID です。

プラグインはメッセージに cc（追加受信者）と replyTo を設定できます。プロバイダーは存在するとき両方を配信すべきです。cc を黙って捨てるプロバイダーでは、それらの受信者にメールが届きません。

`email:afterSend`

Capability: hooks.email-events:register

配信成功後に実行される 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,
    });
  },
}

イベントと戻り値

email:afterSend は email:deliver と同じ message と source フィールドを受け取ります。戻り値はありません。

コメントフック

コメントフックは comment:beforeCreate → comment:moderate → comment:afterCreate の順で実行されます。comment:afterModerate は、管理者または権限のあるプラグインがコメントのステータスを変更したときに別途実行されます。

コメント保存後、フックは次のレコード形状を受け取ります。

interface StoredComment {
	id: string;
	collection: string;
	contentId: string;
	parentId: string | null;
	authorName: string;
	authorEmail: string;
	authorUserId: string | null;
	body: string;
	status: string;
	moderationMetadata: Record<string, unknown> | null;
	createdAt: string;
	updatedAt: string;
}

`comment:beforeCreate`

Capability: users:read

コメント保存前のミドルウェアフックです。コメントの付加、検証、拒否に使います。

hooks: {
  "comment:beforeCreate": async (event, ctx) => {
    // Reject comments with links
    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`

Capability: users:read | 排他: はい

コメントを承認済み（approved）、保留（pending）、スパム（spam）のいずれにするか決定します。アクティブなモデレーションプロバイダーは 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: { /* same as 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 }

アクティブなモデレーター

EmDash にはコレクションのコメント設定を適用する組み込みモデレーターがあります。comment:moderate を提供するプラグインがちょうど 1 つなら、EmDash は組み込みの代わりにそのプラグインを選び、選択を保存します。複数プラグインが提供し保存された選択がなければ、EmDash はどれも選ばず、新規コメントはレビュー待ちになります。組み込みモデレーターを含む保存済みの選択は、選ばれたモデレーターが有効な間有効です。

`comment:afterCreate`

Capability: users:read

コメント保存後に実行される fire-and-forget 型のフックです。通知に使います。メール送信には email:send capability と設定済みの email:deliver プロバイダーも必要です。両方がなければ ctx.email は undefined です。

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

イベントと戻り値

interface CommentAfterCreateEvent {
	comment: StoredComment;
	metadata: Record<string, unknown>;
	content: { id: string; collection: string; slug: string; title?: string };
	contentAuthor?: { id: string; name: string | null; email: string };
}

フックに戻り値はありません。

`comment:afterModerate`

Capability: users:read

管理者またはプラグインがコメントのステータスを変更した後に実行されます。成功した遷移ではフックは 1 回実行されます。フックエラーはログに記録され、ステータス変更は取り消されません。

イベント

interface CommentAfterModerateEvent {
	comment: StoredComment;
	previousStatus: string;
	newStatus: string;
	moderator: { id: string; name: string | null };
	origin?:
		| { source: "admin"; userId: string }
		| { source: "plugin"; pluginId: string };
}

フックに戻り値はありません。

ページフック

ページフックは公開ページのレンダリング時に実行されます。プラグインがメタデータとスクリプトを注入できます。

両方のページフックは現在の公開ページコンテキストを受け取ります。

interface PublicPageContext {
	url: string;
	path: string;
	locale: string | null;
	kind: "content" | "custom";
	pageType: string;
	title: string | null;
	pageTitle?: string | null;
	description: string | null;
	canonical: string | null;
	image: string | null;
	content?: { collection: string; id: string; slug: string | null };
	seo?: {
		ogTitle?: string | null;
		ogDescription?: string | null;
		ogImage?: string | null;
		robots?: string | null;
	};
	articleMeta?: {
		publishedTime?: string | null;
		modifiedTime?: string | null;
		author?: string | null;
	};
	siteName?: string;
	breadcrumbs?: Array<{ name: string; url: string }>;
	siteUrl?: string;
}

interface PageMetadataEvent { page: PublicPageContext }
interface PageFragmentEvent { page: PublicPageContext }

`page:metadata`

Capability: 不要

ページ head に meta タグ、Open Graph プロパティ、JSON-LD 構造化データ、link タグを追加できます。

hooks: {
  "page:metadata": async (event, ctx) => {
    return [
      { kind: "meta", name: "generator", content: "EmDash" },
      { kind: "property", property: "og:site_name", content: event.page.siteName ?? "My Site" },
      { 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: "canonical" | "alternate" | "author" | "license" | "nlweb" | "site.standard.document";
			href: string;
			hreflang?: string;
			key?: string;
	  }
	| {
			kind: "jsonld";
			id?: string;
			graph: Record<string, unknown> | Array<Record<string, unknown>>;
	  };

key フィールドでコントリビューションを重複排除します。同じ key のうち最後のものだけが使われます。

プラグインが追加するものがなければ、1 件、配列、または null を返します。

`page:fragments`

Capability: hooks.page-fragments:register

ページにスクリプトまたは 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;
		};

プラグインが追加するものがなければ、1 件の fragment コントリビューション、配列、または null を返します。

フックの設定

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

hooks: {
  // Simple handler
  "content:afterSave": async (event, ctx) => { ... },

  // With configuration
  "content:beforeSave": {
    priority: 50,        // Lower runs first (default: 100)
    timeout: 10000,      // Max execution time in ms (default: 5000)
    dependencies: [],    // Run after these plugins
    errorPolicy: "abort", // "continue" or "abort" (default)
    handler: async (event, ctx) => { ... },
  },
}

設定オプション

オプション	型	デフォルト	説明
`priority`	`number`	`100`	実行順（小さいほど先）
`timeout`	`number`	`5000`	最大実行時間（ミリ秒）
`dependencies`	`string[]`	`[]`	先に実行する必要があるプラグイン ID
`errorPolicy`	`string`	`"abort"`	エラーを無視するには `"continue"`
`exclusive`	`boolean`	`false`	アクティブプロバイダーは 1 プラグインのみ（`email:deliver`、`comment:moderate` などのプロバイダーパターンフック向け）

プラグインコンテキスト

すべてのフックは、プラグイン 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;
}

各コンテキスト API に必要な capability はプラグイン capability を参照してください。

エラー処理

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

"abort"（デフォルト）— 実行を停止し、該当する場合はトランザクションをロールバック
"continue" — エラーをログに記録し、次のフックへ進む

hooks: {
  "content:beforeSave": {
    errorPolicy: "continue", // Don't block save if this fails
    handler: async (event, ctx) => {
      try {
        await ctx.http?.fetch("https://api.example.com/validate");
      } catch (error) {
        ctx.log.warn("Validation service unavailable", error);
      }
    },
  },
}

実行順序

フックは次の順序で実行されます。

priority でソート（昇順）
dependencies を持つプラグインは依存先の後に実行
同じ priority 内の順序は決定的だが、仕様上は未指定

// This runs first (priority 10)
{ priority: 10, handler: ... }

// This runs second (priority 50)
{ priority: 50, handler: ... }

// This runs last (default priority 100)
{ handler: ... }