ネイティブプラグインの配布

ネイティブプラグインは 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 設定ページに変換してサンドボックス化できます。トレードオフについてはプラグイン形式の選択を参照してください。