Portable Text 렌더링 컴포넌트

플러그인은 Portable Text 에디터에 커스텀 블록 타입을 추가할 수 있습니다 — YouTube 임베드, 코드 스니펫, 이미지 갤러리 등 기본 블록 세트에서 다루지 않는 모든 것입니다. 샌드박스 플러그인은 이러한 블록의 편집 UI를 선언할 수 있지만(Block Kit 필드 사용), 공개 사이트에서 이를 렌더링하는 Astro 컴포넌트는 빌드 시 npm에서 로드되어야 합니다. 이것이 네이티브 플러그인이 필요한 부분입니다.

플러그인이 편집 측 필드만 필요하고 다른 사람이 렌더링 컴포넌트를 제공하는 경우(또는 사이트가 로컬에서 제공하는 경우), 샌드박스 상태를 유지할 수 있습니다. 플러그인이 렌더링 컴포넌트도 함께 제공해야 하는 경우 네이티브여야 합니다.

블록 타입 선언

샌드박스 및 네이티브 플러그인 모두 블록 타입을 선언할 수 있습니다. 네이티브 플러그인은 definePlugin() 내의 admin.portableTextBlocks 아래에서 이를 수행합니다:

admin: {
	portableTextBlocks: [
		{
			type: "youtube",
			label: "YouTube Video",
			icon: "video",                       // video, code, link, link-external
			placeholder: "Paste YouTube URL...",
			fields: [                            // Block Kit fields for the editing UI
				{ type: "text_input", action_id: "id", label: "YouTube URL" },
				{ type: "text_input", action_id: "title", label: "Title" },
				{ type: "text_input", action_id: "poster", label: "Poster Image URL" },
			],
		},
	],
},

각 블록 타입은 다음을 정의합니다:

type — 블록 타입 이름(Portable Text _type에서 사용됨).
label — 에디터의 슬래시 명령 메뉴에 표시되는 이름.
icon — video, code, link 또는 link-external. 기본적으로 일반 큐브로 폴백됩니다.
placeholder — 입력 플레이스홀더 텍스트.
fields — 편집을 위한 Block Kit 폼 필드. 생략하면 간단한 URL 입력이 표시됩니다.

공개 사이트에서 렌더링

공개 사이트에서 블록 타입을 렌더링하려면 componentsEntry에서 Astro 컴포넌트를 내보냅니다. 내보내기 이름은 반드시 blockComponents여야 합니다:

import YouTube from "./YouTube.astro";
import CodePen from "./CodePen.astro";

export const blockComponents = {
	youtube: YouTube,
	codepen: CodePen,
};

디스크립터에 componentsEntry를 설정합니다:

export function myPlugin(): PluginDescriptor {
	return {
		id: "embeds",
		version: "1.0.0",
		format: "native",
		entrypoint: "@my-org/embeds",
		componentsEntry: "@my-org/embeds/astro",
	};
}

EmDash는 플러그인 블록 컴포넌트를 <PortableText>에 자동으로 병합합니다 — 사이트 작성자는 아무것도 가져올 필요가 없습니다. 사용자가 제공한 컴포넌트(사이트의 <PortableText>에서 components prop으로 선언됨)는 플러그인 기본값보다 우선합니다.

패키지 내보내기

package.json에 ./astro 내보내기를 추가합니다:

{
	"exports": {
		".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },
		"./admin": { "types": "./dist/admin.d.ts", "import": "./dist/admin.js" },
		"./astro": { "types": "./dist/astro/index.d.ts", "import": "./dist/astro/index.js" }
	}
}

./astro 내보내기는 서버 측(Astro SSR)이고, ./admin 내보내기는 브라우저 측(React)이며, "." 내보내기는 디스크립터 + createPlugin입니다. 다른 환경을 위해 번들되므로 별도의 파일에 보관하세요.

샌드박스 친화적인 변형

플러그인을 샌드박스로 유지하면서도 기본 렌더링 경험을 제공하고 싶다면 일반적인 패턴은 다음과 같습니다:

마켓플레이스에 샌드박스 플러그인(편집 필드만)을 배포합니다.
Astro 렌더링 컴포넌트를 제공하는 별도의 컴패니언 네이티브 패키지를 npm에 배포합니다.
둘 다 문서화: 최종 사용자는 마켓플레이스에서 샌드박스 플러그인을 설치하고 렌더링을 위한 컴패니언 패키지를 npm install합니다.

이것은 원스텝 설치를 에디터 측을 샌드박스로 유지하는 것과 교환합니다. 블록 렌더링이 관련된 경우 완전히 네이티브로 가는 것이 더 간단하지만, 이 분리는 여전히 옵션으로 남아 있습니다.