Hooks

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

このページでは、sandboxed（標準形式）プラグインについて説明します。Hooksはネイティブプラグインでも同じように機能しますが、唯一の違いは、ネイティブプラグインは page:fragments も登録できることです。sandboxedプラグインではできません。

Hookのシグネチャ

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

async (event: EventType, ctx: PluginContext) => ReturnType;

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

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" });
},

Event: {} — Returns: Promise<void>

plugin:activate

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

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

Event: {} — Returns: Promise<void>

plugin:deactivate

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

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

Event: {} — Returns: 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));
	}
},

Event: { deleteData: boolean } — Returns: 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;
},

Event: { content, collection, isNew } — Returns: 変更されたコンテンツまたは 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 }),
		});
	}
},

Event: { content, collection, isNew } — Returns: 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;
},

Event: { id, collection } — Returns: boolean | void

content:afterDelete

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

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

Event: { id, collection } — Returns: Promise<void>

content:afterPublish

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

Event: { content, collection } — Returns: Promise<void>

content:afterUnpublish

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

Event: { content, collection } — Returns: 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}` };
},

Event: { file: { name, type, size } } — Returns: 変更されたファイルまたは void

media:afterUpload

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

Event: { media: { id, filename, mimeType, size, url, createdAt } } — Returns: Promise<void>

パブリックページhooks

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

page:metadata

型付きメタデータを <head> に提供します — メタタグ、OpenGraphプロパティ、許可リストの <link> rels、およびJSON-LD。sandboxedプラグインとネイティブプラグインの両方で利用可能です。 コアは貢献を検証、重複排除、レンダリングします。プラグインは構造化データを返し、生の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,
		},
	};
},

Event:

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

Returns: PageMetadataContribution | PageMetadataContribution[] | null

貢献の種類:

すべての重複排除キーに対して最初の貢献が優先されます。Link rel はセキュリティでロックされた許可リスト（canonical、alternate、author、license、nlweb、site.standard.document）に制限されています。href はHTTPまたはHTTPSである必要があります。

page:fragments

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

sandboxedプラグインは、この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リファレンスを参照してください。