Native Plugins verteilen

Native Plugins werden über npm verteilt, nicht über den Marketplace. Es gibt keinen Bundler, kein Manifest, keinen Sicherheitsaudit-Schritt — nur ein reguläres npm-Paket, das eine Descriptor-Factory plus createPlugin exportiert. Site-Betreiber installieren es mit npm install und registrieren es in astro.config.mjs.

Paketstruktur

Ein typisches natives Plugin-Paket:

@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"
	}
}

Überspringen Sie die ./admin und ./astro Exports, wenn Ihr Plugin diese nicht benötigt.

Build-Konfiguration

Native Plugins werden als ES-Module ausgeliefert. Die meisten Autoren verwenden tsdown (oder tsup) mit TypeScript. Externalisieren Sie react, emdash und @emdash-cms/admin, damit sie nicht in Ihre Ausgabe gebündelt werden:

export default {
	entry: {
		index: "src/index.ts",
		admin: "src/admin.tsx",
	},
	format: "esm",
	dts: true,
	external: ["react", "react-dom", "emdash", "@emdash-cms/admin"],
};

Wenn Sie Astro-Komponenten für Portable Text Rendering ausliefern, benötigen diese kein Bundling — Astro verwendet die .astro Quelldateien direkt. Listen Sie das astro/ Verzeichnis unter files auf, damit es im npm-Tarball enthalten ist.

Versionierung

Verwenden Sie semantische Versionierung. Das Erhöhen einer Hauptversion ist ein Signal an Betreiber, dass sie beim Upgrade möglicherweise Änderungen vornehmen müssen. Die Form von definePlugin() und die Plugin-Kontext-API sind stabil, aber wenn Sie das Hook-Verhalten, Capability-Anforderungen oder das Settings-Schema Ihres Plugins auf eine Weise ändern, die bestehende Installationen betrifft, ist das eine Breaking Change.

Capabilities sind Teil des Oberflächenvertrags des Plugins. Das Hinzufügen einer Capability in einem Nicht-Hauptrelease bedeutet, dass bestehende Betreiber upgraden und stillschweigend eine neue Capability erhalten — das ist für ein Sandbox-Plugin in Ordnung, wo der Zustimmungsdialog erneut erscheint, aber native Plugins haben keinen Zustimmungsablauf. Behandeln Sie Capability-Ergänzungen als Hauptversions-Bump für native Plugins oder dokumentieren Sie sie sehr prominent in den Release-Notizen.

README und Dokumentation

Ein gutes Plugin-README umfasst:

• Was das Plugin tut, in einem Satz.
• Wie man es installiert (npm install ... und das astro.config.mjs Snippet mit dem Import).
• Welche Capabilities es deklariert und wofür es sie verwendet.
• Alle erforderlichen Astro-Template-Änderungen (z.B. <EmDashHead /> für page:metadata, <EmDashBodyEnd /> für page:fragments).
• Einstellungen und was jede einzelne steuert.
• Migrationshinweise zwischen Hauptversionen.

Auf npm veröffentlichen

npm version patch     # or minor/major
npm publish --access public

Für Scoped-Pakete ist --access public bei der ersten Veröffentlichung erforderlich (npm setzt Scoped-Pakete standardmäßig auf privat).

Lokale Entwicklung gegen eine Host-Site

Wenn Sie an einem Plugin iterieren, verlinken Sie es mit einer Test-Site, anstatt bei jeder Änderung neu zu veröffentlichen:

# 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

Registrieren Sie dann das Plugin in der astro.config.mjs der Test-Site und starten Sie den Dev-Server. Hook-Handler werden bei der nächsten Anfrage nach Abschluss von pnpm build ausgeführt.

Marketplace? Nein.

Native Plugins können nicht im EmDash Marketplace veröffentlicht werden. Der Marketplace ist nur für Sandbox-Plugins: Jedes veröffentlichte Plugin durchläuft emdash plugin bundle (das validiert, dass der Backend-Code in sich geschlossen ist, keine Node.js Built-ins importiert und unter den Größenlimits bleibt), erhält ein Sicherheitsaudit und läuft bei der Installation in der Sandbox-Laufzeit.

Wenn Sie die Vertriebsfläche des Marketplace wünschen, aber Ihr Plugin derzeit nur-native Features verwendet, fragen Sie sich, ob Sie diese wirklich benötigen — viele Plugins können page:fragments entfernen oder von settingsSchema auf eine Block Kit Settings-Seite umstellen und sandboxfähig werden. Siehe Ein Plugin-Format wählen für die Abwägungen.