네이티브 플러그인 배포

네이티브 플러그인은 마켓플레이스가 아닌 npm을 통해 배포됩니다. 번들러도, 매니페스트도, 보안 감사 단계도 없습니다 — 설명자 팩토리와 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

{
	"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 설정 페이지로 변환하여 샌드박스화할 수 있습니다. 장단점은 플러그인 형식 선택을 참조하세요.