훅 | EmDash CMS Everything

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

이 페이지는 샌드박스 플러그인을 다룹니다. 훅은 네이티브 플러그인에서도 동일하게 작동합니다. 네이티브 플러그인은 추가로 page:fragments를 등록할 수 있습니다.

훅 시그니처

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

async (event, ctx) => ReturnType;

event — 방금 발생한 일에 대한 데이터 (콘텐츠 저장, 미디어 업로드, 라이프사이클 전환 등)
ctx — 스토리지, KV, 로깅 및 기능 제어 API를 가진 PluginContext

기본 내보내기의 satisfies SandboxedPlugin이 훅 이름(전체 정규 이벤트 타입)에서 event를 추론하고 ctx를 PluginContext로 추론하므로 핸들러에는 매개변수 어노테이션이 필요하지 않습니다. 헬퍼에서 이름으로 이벤트 타입을 참조하려면 emdash/plugin에서 가져오세요.

훅 구성

훅은 단순 핸들러로 또는 구성 객체로 감싸서 선언할 수 있습니다:

단순

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

구성 옵션

옵션	타입	기본값	설명
`priority`	`number`	`100`	실행 순서. 낮은 숫자가 먼저 실행됩니다.
`timeout`	`number`	`5000`	최대 실행 시간(밀리초).
`dependencies`	`string[]`	`[]`	이 훅 전에 실행되어야 하는 플러그인 ID.
`errorPolicy`	`"abort" \| "continue"`	`"abort"`	오류 시 파이프라인을 중지할지 여부.
`exclusive`	`boolean`	`false`	하나의 플러그인만 활성 제공자가 될 수 있습니다. `email:deliver`와 `comment:moderate`에 사용됩니다.
`handler`	`function`	—	훅 핸들러 함수. 필수.

라이프사이클 훅

플러그인 설치, 활성화, 비활성화, 제거 시 실행됩니다.

`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>

콘텐츠 훅

사이트 콘텐츠의 생성, 업데이트, 삭제 작업 시 실행됩니다.

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

이벤트: { 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>