分發原生外掛程式

原生外掛程式透過 npm 分發。原生外掛程式是一個常規的 npm 套件，匯出一個描述符工廠以及 createPlugin。網站管理者使用 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 原始檔。在 files 下列出 astro/ 目錄，以便它們包含在 npm tarball 中。

版本控制

使用語意化版本控制。提升主版本號是向管理者發出的訊號，表明他們在升級時可能需要進行變更。definePlugin() 的形式和外掛程式上下文 API 是穩定的，但如果你以影響現有安裝的方式變更外掛程式的掛鉤行為、功能要求或設定結構描述，那就是破壞性變更。

功能是外掛程式表面契約的一部分。在非主版本中新增一個功能意味著現有管理者升級並靜默授予新功能 — 這對於沙盒外掛程式來說沒問題，因為同意對話方塊會重新提示，但原生外掛程式沒有同意流程。將功能新增視為原生外掛程式的主版本提升，或在發佈說明中非常顯著地記錄它們。

README 和文件

一個好的外掛程式 README 應涵蓋：

• 外掛程式的功能，用一句話描述。
• 如何安裝它（npm install ... 和帶有匯入的 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 設定頁面。有關權衡，請參閱選擇外掛程式格式。