Hooks

Hooks는 플러그인이 이벤트에 응답하여 코드를 실행할 수 있게 합니다. 모든 hooks는 이벤트 객체와 플러그인 컨텍스트를 받으며, 플러그인 정의 시점에 선언됩니다 — 런타임에 동적 등록은 없습니다.

이 페이지는 sandboxed (표준 형식) 플러그인을 다룹니다. Hooks는 네이티브 플러그인에서도 동일하게 작동합니다. 유일한 차이점은 네이티브 플러그인은 page:fragments도 등록할 수 있다는 것입니다. sandboxed 플러그인은 할 수 없습니다.

Hook 시그니처

모든 hook 핸들러는 두 개의 인수를 받습니다:

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를 반환합니다. 취소하려면 throw하세요.

"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

파일이 업로드되기 전에 실행됩니다. 수정된 파일 메타데이터를 반환하거나 취소하려면 throw하세요.

"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 플러그인과 네이티브 플러그인 모두에서 사용 가능합니다. 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,
		},
	};
},

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이 throw하거나 타임아웃될 때:

• 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 레퍼런스를 참조하세요.