E EmDash CMS Everything Guides, use cases, plugins, templates
한국어

플러그인 CLI로 마이그레이션

이 페이지

이 가이드는 이전 definePlugin() 형식으로 작성된 샌드박스 플러그인 작성자를 위한 것입니다. 주요 변경 사항을 순서대로 진행하세요. 이러한 변경 사항은 런타임에서 훅이나 라우트가 작동하는 방식을 변경하지 않으며, 플러그인이 선언, 빌드 및 게시되는 방식을 변경합니다.

각 패키지의 전체 변경 사항 목록은 EmDash changelog를 참조하세요.

주요 변경 사항

이름 변경: @emdash-cms/registry-cli가 이제 @emdash-cms/plugin-cli입니다

이전 릴리스에서는 CLI를 emdash-registry 바이너리와 함께 @emdash-cms/registry-cli로 제공했습니다.

패키지는 이제 @emdash-cms/plugin-cli이고 바이너리는 emdash-plugin입니다. 이전 패키지는 더 이상 게시되지 않습니다.

무엇을 해야 하나요?

종속성을 교체하세요:

pnpm remove @emdash-cms/registry-cli
pnpm add -D @emdash-cms/plugin-cli

호출하는 모든 곳에서 emdash-registry를 emdash-plugin으로 교체하세요. 모든 하위 명령은 이름을 유지하며(bundle, publish, login, whoami, switch, validate), init, build, dev가 추가됩니다. 플러그인 CLI를 참조하세요.

변경: 샌드박스 플러그인은 satisfies SandboxedPlugin으로 정의됩니다

이전 릴리스에서는 emdash에서 가져온 definePlugin()으로 플러그인의 훅과 라우트를 래핑하고 각 핸들러의 매개변수를 수동으로 주석 처리했습니다.

샌드박스 플러그인은 이제 satisfies SandboxedPlugin으로 주석 처리된 단순한 기본 내보내기입니다. 타입은 번들러가 제거하는 타입 전용 진입점인 emdash/plugin에서 제공됩니다. TypeScript는 훅 또는 라우트 이름에서 각 핸들러의 event와 ctx를 추론하므로 핸들러 매개변수에 주석이 필요하지 않습니다.

무엇을 해야 하나요?

플러그인의 소스 파일에 네 가지 변경 사항을 적용하세요. 가져오기를 교체하세요:

import { definePlugin, type ContentHookEvent, type PluginContext } from "emdash";
import type { SandboxedPlugin } from "emdash/plugin";

definePlugin() 래퍼를 단순한 객체와 satisfies 주석으로 교체하세요:

export default definePlugin({ /* hooks, routes */ });
export default { /* hooks, routes */ } satisfies SandboxedPlugin;

모든 핸들러에서 매개변수 주석을 제거하세요:

handler: async (event: ContentHookEvent, ctx: PluginContext) => {
handler: async (event, ctx) => {

결과는 단일 기본 내보내기 객체입니다:

import type { SandboxedPlugin } from "emdash/plugin";

export default {
	hooks: {
		"content:beforeSave": {
			handler: async (event, ctx) => {
				return event.content;
			},
		},
	},
} satisfies SandboxedPlugin;

헬퍼 함수에서 이벤트 타입의 이름을 지정하려면 emdash/plugin에서 가져오세요:

import type { ContentHookEvent, PluginContext } from "emdash/plugin";

핸들러의 event는 항상 해당 훅의 정규 타입입니다. 더 좁은 인터페이스로 핸들러에 주석을 다는 것은 더 이상 타입 검사를 통과하지 않습니다. 타입 시스템 외부에서 오는 데이터에 대한 올바른 접근 방식인 typeof 검사 또는 가드를 사용하여 런타임에 의존하는 모든 필드를 검증하세요.

변경: 플러그인은 src/plugin.ts와 emdash-plugin.jsonc입니다

이전 릴리스에서는 플러그인을 두 파일로 분할했습니다: src/index.ts는 PluginDescriptor(id, version, capabilities, storage, entrypoint)를 반환하고, src/sandbox-entry.ts는 훅과 라우트를 보유했습니다.

플러그인은 이제 하나의 런타임 파일 src/plugin.ts(훅과 라우트)와 수동으로 편집된 매니페스트 emdash-plugin.jsonc(신원 및 신뢰 계약)입니다. entrypoint 및 format 필드는 사라졌으며 빌드가 이를 연결합니다.

무엇을 해야 하나요?

위의 형식을 사용하여 훅과 라우트를 src/plugin.ts로 이동하세요. 설명자의 메타데이터를 package.json 옆의 emdash-plugin.jsonc로 이동하세요. 설명자 id는 매니페스트 slug가 되고, capabilities, allowedHosts, storage는 형식을 유지하며, version은 package.json에서 읽으므로 생략하세요.

다음 예제는 스토리지 컬렉션을 선언한 설명자의 매니페스트 동등물을 보여줍니다:

{
	"$schema": "./node_modules/@emdash-cms/plugin-cli/schemas/emdash-plugin.schema.json",

	"slug": "plugin-hello",
	"publisher": "did:plc:abc123def456",

	"license": "MIT",
	"author": { "name": "Jane Doe", "url": "https://example.com" },
	"security": { "email": "[email protected]" },

	"capabilities": [],
	"allowedHosts": [],
	"storage": { "events": { "indexes": ["timestamp"] } }
}

모든 필드에 대해서는 플러그인 매니페스트를, publisher 필드에 대해서는 퍼블리셔 고정을 참조하세요.

package.json에서 "./sandbox" 내보내기를 빌드된 런타임 파일로 지정하세요:

"./sandbox": "./dist/sandbox-entry.mjs"
"./sandbox": "./dist/plugin.mjs"

매니페스트를 files에 추가하여 패키지와 함께 제공되도록 하세요:

"files": ["dist"]
"files": ["dist", "emdash-plugin.jsonc"]

변경: emdash-plugin build로 빌드

이전 릴리스에서는 수동으로 작성된 tsdown 스크립트로 두 소스 파일을 빌드했습니다.

emdash-plugin build는 emdash-plugin.jsonc와 src/plugin.ts를 읽고 dist/ 아티팩트를 생성합니다. emdash-plugin dev는 감시하고 다시 빌드합니다.

무엇을 해야 하나요?

빌드 스크립트를 교체하고 감시 스크립트를 추가하세요:

"scripts": {
	"build": "tsdown src/index.ts src/sandbox-entry.ts --format esm --dts --clean"
	"build": "emdash-plugin build",
	"dev": "emdash-plugin dev"
}

그런 다음 검증하고 빌드하세요:

emdash-plugin validate
emdash-plugin build

제거됨: emdash의 표준 형식 타입 및 함수 내보내기

이전 릴리스에서는 StandardPluginDefinition, StandardHookHandler, StandardHookEntry, StandardRouteHandler, StandardRouteEntry 및 함수 isStandardPluginDefinition을 emdash에서 내보냈습니다.

이들은 제거되었습니다. 이전 definePlugin 형식의 헬퍼 별칭이었습니다.

무엇을 해야 하나요?

동일한 목적으로 emdash/plugin의 SandboxedPlugin을 사용하세요. 샌드박스 플러그인의 기본 내보내기는 이미 satisfies SandboxedPlugin 주석으로 타입이 지정되어 있으므로 isStandardPluginDefinition에 대한 대체는 없습니다. 필요한 경우 구조({ hooks?, routes? })로 플러그인을 식별하세요.

이름 변경: 런타임 타입 SandboxedPlugin이 이제 SandboxedPluginInstance입니다

이것은 @emdash-cms/cloudflare와 같은 사용자 정의 SandboxRunner의 작성자에게만 영향을 미칩니다. 대부분의 플러그인 작성자는 건너뛸 수 있습니다.

emdash의 SandboxedPlugin은 이제 작성자 지향 소스 형식을 나타냅니다. SandboxRunner.load가 반환하는 런타임 핸들은 SandboxedPluginInstance입니다.

무엇을 해야 하나요?

샌드박스 러너를 타입 지정하거나 런타임 플러그인 핸들을 보유하기 위해 emdash에서 SandboxedPlugin을 가져오는 경우 가져오기를 SandboxedPluginInstance로 변경하세요:

import type { SandboxedPlugin } from "emdash";
import type { SandboxedPluginInstance } from "emdash";

사용자에게 알리기

플러그인을 설치하는 사이트도 가져오기를 변경해야 합니다. 새로운 형식을 안내하세요: 중괄호와 ()를 제거합니다.

import { helloPlugin } from "@my-org/plugin-hello";
import hello from "@my-org/plugin-hello";

export default defineConfig({
	integrations: [
		emdash({
			sandboxed: [helloPlugin()],
			sandboxed: [hello],
		}),
	],
});

플러그인이 팩토리를 통해 구성을 수락한 경우 해당 구성은 관리 UI의 플러그인 설정으로 이동합니다. 런타임에 ctx.kv 또는 설정을 통해 읽으세요. 설정을 참조하세요.

다음