Hooks

Hooksを使用すると、プラグインがイベントに応じてコードを実行できます。すべてのhooksはイベントオブジェクトとプラグインコンテキストを受け取り、プラグイン定義時に宣言されます。実行時の動的な登録はありません。

このページではサンドボックス化されたプラグインについて説明します。Hooksはネイティブプラグインでも同じように機能します。ネイティブプラグインはさらにpage:fragmentsを登録できます。

Hookシグネチャ

すべてのhookハンドラーは2つの引数を取ります：

async (event, ctx) => ReturnType;

• event — 何が起こったかに関するデータ（コンテンツの保存、メディアのアップロード、ライフサイクルの遷移など）
• ctx — ストレージ、KV、ロギング、機能制御されたAPIを持つPluginContext

デフォルトエクスポートのsatisfies SandboxedPluginは、hook名（完全な正規のイベントタイプ）からeventを、PluginContextとしてctxを推論するため、ハンドラーはパラメータの注釈を必要としません。ヘルパーで名前でイベントタイプを参照するには、emdash/pluginからインポートしてください。

Hook設定

Hookは単純なハンドラーとして宣言するか、設定オブジェクトでラップできます：

hooks: {
	"content:afterSave": async (event, ctx) => {
		ctx.log.info("Content saved");
	},
},

hooks: {
	"content:afterSave": {
		priority: 100,
		timeout: 5000,
		dependencies: ["audit-log"],
		errorPolicy: "continue",
		handler: async (event, ctx) => {
			ctx.log.info("Content saved");
		},
	},
},

設定オプション

ライフサイクルhooks

プラグインのインストール、アクティブ化、非アクティブ化、削除時に実行されます。

plugin:install

プラグインが初めてサイトに追加されたときに一度実行されます。

"plugin:install": async (_event, ctx) => {
	ctx.log.info("Installing plugin...");
	await ctx.kv.set("settings:enabled", true);
	await ctx.storage.items.put("default", { name: "Default Item" });
},

イベント： {} — 戻り値： Promise<void>

plugin:activate

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

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

イベント： {} — 戻り値： Promise<void>

plugin:deactivate

プラグインが無効化されたとき（削除されていない）に実行されます。

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

イベント： {} — 戻り値： Promise<void>

plugin:uninstall

プラグインがサイトから削除されるときに実行されます。

"plugin:uninstall": async (event, ctx) => {
	ctx.log.info("Uninstalling plugin...");
	if (event.deleteData) {
		const result = await ctx.storage.items.query({ limit: 1000 });
		await ctx.storage.items.deleteMany(result.items.map((i) => i.id));
	}
},

イベント： { deleteData: boolean } — 戻り値： Promise<void>

コンテンツhooks

サイトコンテンツの作成、更新、削除操作中に実行されます。

content:beforeSave

コンテンツが保存される前に実行されます。変更されたコンテンツを返すか、変更しない場合はvoidを返します。キャンセルするにはエラーをスローします。

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

	if (collection === "posts" && !content.title) {
		throw new Error("Posts require a title");
	}

	if (typeof content.slug === "string") {
		content.slug = content.slug.toLowerCase().replace(/\s+/g, "-");
	}

	return content;
},

イベント： { content, collection, isNew } — 戻り値： 変更されたコンテンツまたはvoid。

content:afterSave

コンテンツが正常に保存された後に実行されます。通知、ロギング、外部同期などの副作用に使用します。

"content:afterSave": async (event, ctx) => {
	ctx.log.info(`${event.isNew ? "Created" : "Updated"} ${event.collection}/${event.content.id}`);

	if (ctx.http) {
		await ctx.http.fetch("https://api.example.com/webhook", {
			method: "POST",
			body: JSON.stringify({ event: "content:save", id: event.content.id }),
		});
	}
},

イベント： { content, collection, isNew } — 戻り値： Promise<void>

content:beforeDelete

コンテンツが削除される前に実行されます。キャンセルするにはfalseを返します。trueまたはvoidは許可します。

"content:beforeDelete": async (event, ctx) => {
	if (event.collection === "pages" && event.id === "home") {
		ctx.log.warn("Cannot delete home page");
		return false;
	}
	return true;
},

イベント： { id, collection } — 戻り値： boolean | void

content:afterDelete

コンテンツが正常に削除された後に実行されます。

"content:afterDelete": async (event, ctx) => {
	await ctx.storage.cache.delete(`${event.collection}:${event.id}`);
},

イベント： { id, collection } — 戻り値： Promise<void>

content:afterPublish

コンテンツが下書きから公開に昇格された後に実行されます。content:read機能が必要です。

イベント： { content, collection } — 戻り値： Promise<void>

content:afterUnpublish

コンテンツが公開から下書きに戻された後に実行されます。content:read機能が必要です。

イベント： { content, collection } — 戻り値： Promise<void>

メディアhooks

media:beforeUpload

ファイルがアップロードされる前に実行されます。変更されたファイルメタデータを返すか、キャンセルするにはエラーをスローします。

"media:beforeUpload": async (event, ctx) => {
	if (!event.file.type.startsWith("image/")) {
		throw new Error("Only images are allowed");
	}
	if (event.file.size > 10 * 1024 * 1024) {
		throw new Error("File too large");
	}
	return { ...event.file, name: `${Date.now()}-${event.file.name}` };
},

イベント： { file: { name, type, size } } — 戻り値： 変更されたファイルまたはvoid

media:afterUpload

ファイルが正常にアップロードされた後に実行されます。

イベント： { media: { id, filename, mimeType, size, url, createdAt } } — 戻り値： Promise<void>

公開ページhooks

これらにより、プラグインはレンダリングされた公開ページに貢献できます。テンプレートはemdash/uiから<EmDashHead>、<EmDashBodyStart>、<EmDashBodyEnd>コンポーネントを含めることでオプトインします。

page:metadata

型付きメタデータを<head>に提供します — メタタグ、OpenGraphプロパティ、許可リスト化された<link> rel、JSON-LD。サンドボックスとネイティブの両方のプラグインで利用可能。 Coreは貢献を検証、重複排除、レンダリングします。プラグインは構造化データを返し、生のHTMLは返しません。

"page:metadata": async (event, ctx) => {
	if (event.page.kind !== "content") return null;

	return {
		kind: "jsonld",
		id: `schema:${event.page.content?.collection}:${event.page.content?.id}`,
		graph: {
			"@context": "https://schema.org",
			"@type": "BlogPosting",
			headline: event.page.pageTitle ?? event.page.title,
			description: event.page.description,
		},
	};
},

イベント：

{
	page: {
		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 };
	}
}

戻り値： PageMetadataContribution | PageMetadataContribution[] | null

貢献の種類：

重複排除キーごとに最初の貢献が優先されます。リンクrelはセキュリティロックされた許可リスト（canonical、alternate、author、license、nlweb、site.standard.document）に制限されます。hrefはHTTPまたはHTTPSでなければなりません。

page:fragments

生のHTML、スクリプト、またはスタイルシートをページ挿入ポイントに提供します。ネイティブプラグインのみ。

サンドボックスプラグインはこのhookを使用できません。その出力は訪問者のブラウザでファーストパーティコードとして実行され、サンドボックス境界の外側にあるためです。サンドボックスセーフなページ貢献にはpage:metadataを使用してください。この表面が必要な場合はネイティブプラグイン：ページフラグメントを参照してください。

Hook実行順序

Hooksは次の順序で実行されます：

1. priority値が小さいhooksが最初に実行されます。
2. 優先度が等しい場合、hooksはプラグイン登録順に実行されます。
3. dependenciesを持つhooksは、それらのプラグインが完了するまで待機します。

// Plugin A
"content:afterSave": { priority: 50, handler: async () => {} }

// Plugin B
"content:afterSave": { priority: 100, handler: async () => {} }

// Plugin C
"content:afterSave": {
	priority: 200,
	dependencies: ["plugin-a"],   // waits for A even if its priority would normally be later
	handler: async () => {},
}

エラー処理

hookがエラーをスローするかタイムアウトした場合：

• errorPolicy: "abort" — パイプライン全体が停止し、元の操作が失敗する可能性があります。
• errorPolicy: "continue" — エラーがログに記録され、残りのhooksは引き続き実行されます。

"content:afterSave": {
	timeout: 5000,
	errorPolicy: "continue",
	handler: async (event, ctx) => {
		await ctx.http!.fetch("https://unreliable-api.com/notify");
	},
},

タイムアウト

Hooksのデフォルトは5000msです。より遅い作業の場合はタイムアウトを増やしてください：

"content:afterSave": {
	timeout: 30000,
	handler: async (event, ctx) => {
		// Long-running operation
	},
},

Hookリファレンス

完全なイベントタイプとハンドラーシグネチャについては、Hookリファレンスを参照してください。