네이티브 플러그인 배포

네이티브 플러그인은 npm을 통해 배포됩니다. 네이티브 플러그인은 descriptor factory와 createPlugin을 내보내는 일반 npm 패키지입니다. 사이트 운영자는 npm install로 설치하고 astro.config.mjs에 등록합니다.

패키지 레이아웃

일반적인 네이티브 플러그인 패키지는 다음과 같은 레이아웃을 가집니다:

@my-org/plugin-analytics/
├── src/
│   ├── index.ts          # Descriptor + createPlugin
│   ├── admin.tsx         # React admin components (optional)
│   └── astro/            # Astro components for PT block rendering (optional)
│       └── index.ts
├── dist/                 # build output
├── package.json
├── tsconfig.json
└── README.md

package.json

다음 package.json은 배포 가능한 플러그인에 필요한 빌드 스크립트, 익스포트 및 피어 디펜던시를 선언합니다:

{
	"name": "@my-org/plugin-analytics",
	"version": "0.1.0",
	"type": "module",
	"main": "dist/index.js",
	"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"
		}
	},
	"files": ["dist"],
	"scripts": {
		"build": "tsdown src/index.ts src/admin.tsx --format esm --dts --clean",
		"prepublishOnly": "pnpm build"
	},
	"peerDependencies": {
		"emdash": "*",
		"react": "^18.0.0"
	}
}

플러그인에 필요하지 않은 경우 ./admin 및 ./astro 익스포트를 생략하세요.

빌드 구성

네이티브 플러그인은 ES 모듈로 배포됩니다. 대부분의 작성자는 TypeScript와 함께 tsdown(또는 tsup)을 사용합니다. react, emdash, @emdash-cms/admin을 외부화하여 출력에 번들링되지 않도록 합니다:

export default {
	entry: {
		index: "src/index.ts",
		admin: "src/admin.tsx",
	},
	format: "esm",
	dts: true,
	external: ["react", "react-dom", "emdash", "@emdash-cms/admin"],
};

Portable Text 렌더링을 위한 Astro 컴포넌트를 배포하는 경우 번들링이 필요하지 않습니다 — Astro는 .astro 소스 파일을 직접 소비합니다. npm tarball에 포함되도록 files 아래에 astro/ 디렉토리를 나열하세요.

버전 관리

시맨틱 버전 관리를 사용하세요. 메이저 버전을 올리는 것은 업그레이드 시 변경이 필요할 수 있다는 신호를 운영자에게 보내는 것입니다. definePlugin()의 형태와 플러그인 컨텍스트 API는 안정적이지만, 기존 설치에 영향을 미치는 방식으로 플러그인의 훅 동작, 기능 요구사항 또는 설정 스키마를 변경하는 경우 이는 호환성을 깨는 변경입니다.

기능은 플러그인의 표면 계약의 일부입니다. 메이저가 아닌 릴리스에 추가하면 기존 운영자가 업그레이드하고 새로운 기능을 자동으로 부여받게 됩니다 — 동의 대화 상자가 다시 표시되는 샌드박스 플러그인에는 괜찮지만, 네이티브 플러그인에는 동의 흐름이 없습니다. 네이티브 플러그인의 기능 추가는 메이저 버전 업그레이드로 취급하거나 릴리스 노트에 매우 눈에 띄게 문서화하세요.

README 및 문서

좋은 플러그인 README는 다음을 다룹니다:

• 플러그인이 하는 일을 한 문장으로.
• 설치 방법(npm install ...과 import가 포함된 astro.config.mjs 스니펫).
• 선언하는 기능과 그 용도.
• 필요한 Astro 템플릿 변경사항(예: page:metadata용 <EmDashHead />, page:fragments용 <EmDashBodyEnd />).
• 설정과 각각이 제어하는 것.
• 메이저 버전 간 마이그레이션 노트.

npm에 게시

버전을 올리고 패키지를 게시합니다:

npm version patch     # or minor/major
npm publish --access public

스코프 패키지의 경우 첫 번째 게시 시 --access public이 필요합니다(npm은 기본적으로 스코프 패키지를 비공개로 설정합니다).

호스트 사이트에 대한 로컬 개발

플러그인을 반복 작업할 때 매번 재게시하는 대신 테스트 사이트에 연결하세요:

# In the plugin package
pnpm build --watch

# In the test site
pnpm add file:../plugins/my-plugin
# or with workspaces:
pnpm add @my-org/plugin-analytics --workspace

그런 다음 테스트 사이트의 astro.config.mjs에 플러그인을 등록하고 개발 서버를 실행합니다. 훅 핸들러는 pnpm build가 완료된 후 다음 요청에서 실행됩니다.

마켓플레이스 가용성

네이티브 플러그인은 EmDash 마켓플레이스에 게시할 수 없습니다. 마켓플레이스는 샌드박스 전용입니다: 게시된 모든 플러그인은 emdash plugin bundle을 거치며(백엔드 코드가 독립적이고, Node.js 내장 모듈을 가져오지 않으며, 크기 제한을 유지하는지 검증), 보안 감사를 받고, 설치 시 샌드박스 런타임에서 실행됩니다.

네이티브 전용 기능을 사용하는 플러그인은 때때로 이를 제거하고 샌드박스 가능하게 될 수 있습니다 — 예를 들어 page:fragments를 제거하거나 settingsSchema를 Block Kit 설정 페이지로 변환하여. 절충안에 대해서는 플러그인 형식 선택을 참조하세요.