分发原生插件

原生插件通过 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 设置页面。有关权衡，请参阅选择插件格式。