Native Plugins verteilen

Native Plugins werden über npm verteilt. Ein natives Plugin ist 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 hat folgende Struktur:

@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

Die folgende package.json deklariert die Build-Skripte, Exporte und Peer-Dependencies, die ein verteilbares Plugin benötigt:

{
	"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-Exporte, 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 konsumiert die .astro-Quelldateien direkt. Listen Sie das astro/-Verzeichnis unter files auf, damit sie im npm-Tarball enthalten sind.

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-Context-API sind stabil, aber wenn Sie das Hook-Verhalten, die 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 Surface-Contracts des Plugins. Eine in einem Nicht-Major-Release hinzugefügte Capability bedeutet, dass bestehende Betreiber upgraden und stillschweigend eine neue Capability gewähren — das ist in Ordnung für ein sandboxed Plugin, bei dem der Consent-Dialog erneut auffordert, aber native Plugins haben keinen Consent-Flow. Behandeln Sie Capability-Ergänzungen als Major-Version-Bump für native Plugins oder dokumentieren Sie sie sehr prominent in den Release Notes.

README und Dokumentation

Eine gute Plugin-README deckt ab:

• Was das Plugin macht, 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

Erhöhen Sie die Version und veröffentlichen Sie das Paket:

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

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

Lokale Entwicklung gegen eine Host-Site

Beim Iterieren an einem Plugin verknüpfen Sie es mit einer Test-Site, anstatt es 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-Verfügbarkeit

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

Ein Plugin, das native-only Features verwendet, kann diese manchmal entfernen und sandboxable werden — zum Beispiel durch Entfernen von page:fragments oder Konvertieren von settingsSchema zu einer Block Kit-Einstellungsseite. Siehe Ein Plugin-Format wählen für die Abwägungen.