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

ネイティブプラグインは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 ...とインポート付きの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設定ページに変換することによって。トレードオフについてはプラグイン形式の選択を参照してください。