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

이 가이드는 이전 definePlugin() 형태에 맞춰 작성된 샌드박스 플러그인 작성자를 위한 것입니다. 호환성 깨지는 변경을 순서대로 진행하세요. 어느 것도 훅이나 라우트의 런타임 동작을 바꾸지 않으며, 플러그인을 선언·빌드·게시하는 방식을 바꿉니다.

각 패키지의 전체 변경 목록은 릴리스 페이지의 해당 항목을 참고하세요.

호환성 깨지는 변경

이름 변경: @emdash-cms/registry-cli는 이제 @emdash-cms/plugin-cli

이전 릴리스는 CLI를 @emdash-cms/registry-cli로 배포했고, 바이너리는 emdash-registry였습니다.

패키지는 이제 @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가 추가됩니다. The plugin CLI를 참고하세요.

이름 변경: capability 이름은 resource-first 표기를 사용

이전 매니페스트는 read:content, network:fetch 같은 capability 이름을 사용했습니다. 작성 매니페스트는 현재 이름만 받아들이지만, 런타임은 호환 창 동안 이미 게시된 번들의 레거시 이름을 계속 정규화합니다.

무엇을 해야 하나요?

매니페스트의 모든 레거시 이름을 교체하세요.

비어 있지 않은 allowedHosts 목록과 함께 network:request를 사용하세요. 운영자가 런타임에 대상을 선택하는 경우에만 빈 목록과 함께 network:request:unrestricted를 사용하세요. Capabilities and security가 현재 권한과 네트워크 규칙을 설명합니다.

변경: 샌드박스 플러그인은 명시적 SandboxedPlugin 주석을 사용

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

샌드박스 플러그인은 정의를 SandboxedPlugin 타입 상수에 할당하고 그 상수를 default로 export합니다. 타입은 import type으로 emdash/plugin에서 가져오세요. 번들러가 그 import를 지웁니다. 같은 서브패스는 가벼운 런타임 헬퍼 pluginRoute()와 pluginResponse()도 export합니다. TypeScript는 훅 또는 라우트 이름에서 각 핸들러의 event와 ctx를 추론하므로 핸들러 매개변수에 주석이 필요 없습니다. 명시적 주석은 격리된 패키지 매니저 레이아웃에서도 생성된 선언을 이식 가능하게 유지합니다.

무엇을 해야 하나요?

플러그인 소스 파일에 네 가지 변경을 하세요. import를 교체하세요.

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

definePlugin() 래퍼를 명시적으로 타입된 상수로 교체하세요.

export default definePlugin({ /* hooks, routes */ });
const plugin: SandboxedPlugin = { /* hooks, routes */ };

export default plugin;

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

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

결과는 하나의 default-export 객체입니다.

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

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

export default plugin;

헬퍼 함수에서 이벤트 타입에 이름을 붙이려면 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": "security@example.com" },

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

각 필드는 The plugin manifest, publisher 필드는 Publisher pinning을 참고하세요.

package.json에서 "./sandbox" export를 빌드된 런타임 파일로 향하게 하세요.

"./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는 감시하고 다시 빌드합니다.

무엇을 해야 하나요?

빌드 스크립트를 교체하고 watch 스크립트를 추가하세요.

"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의 표준 형식 타입·함수 export

이전 릴리스는 StandardPluginDefinition, StandardHookHandler, StandardHookEntry, StandardRouteHandler, StandardRouteEntry, 함수 isStandardPluginDefinition을 emdash에서 export했습니다.

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

무엇을 해야 하나요?

같은 목적에는 emdash/plugin의 SandboxedPlugin을 사용하세요. 샌드박스 플러그인의 export 정의는 이미 SandboxedPlugin 주석으로 타입되므로 isStandardPluginDefinition 대체는 없습니다. 필요하면 구조({ hooks?, routes? })로 플러그인을 식별하세요.

이름 변경: 샌드박스 러너 핸들은 SandboxedPluginInstance 사용

이는 @emdash-cms/cloudflare 같은 커스텀 SandboxRunner 작성자에게만 영향을 줍니다. 대부분의 플러그인 작성자는 건너뛸 수 있습니다.

작성자 대면 SandboxedPlugin 타입은 emdash/plugin 작성 진입점에서 사용할 수 있습니다. SandboxRunner.load가 반환하는 런타임 핸들은 emdash에서 SandboxedPluginInstance로 export됩니다.

무엇을 해야 하나요?

샌드박스 러너를 타입하거나 런타임 플러그인 핸들을 유지하기 위해 emdash에서 SandboxedPlugin을 import한다면, import를 SandboxedPluginInstance로 바꾸세요.

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

사용자에게 알리기

플러그인을 설치하는 사이트도 import를 바꿔야 합니다. 새 형태를 안내하세요. 중괄호와 ()를 제거합니다.

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

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

플러그인이 팩토리를 통해 구성을 받았다면, 그 구성을 관리 설정 페이지로 옮기고 ctx.settings에서 읽으세요. 샌드박스 플러그인 디스크립터는 plain object이며 생성자 옵션을 받을 수 없습니다. Settings를 참고하세요.

마이그레이션된 플러그인 검증

플러그인 테스트를 실행하고, 작성 매니페스트를 검증하며, 전체 빌드와 번들 검사를 실행하세요.

pnpm test
pnpm exec emdash-plugin validate
pnpm exec emdash-plugin build
pnpm exec emdash-plugin bundle --validate-only

그런 다음 로컬 패키지를 개발 사이트에 설치하고 마이그레이션된 각 훅과 라우트를 실행하세요. 빌드는 이름과 형태를 확인할 수 있지만, 라우트가 의도한 데이터를 반환하는지, 훅이 콘텐츠를 올바르게 보존하는지는 확인할 수 없습니다.

다음

• The plugin manifest
• The plugin CLI
• Your first sandboxed plugin