Distribuire plugin nativi

I plugin nativi si distribuiscono tramite npm, non tramite il marketplace. Non c’è bundler, nessun manifest, nessuno step di audit di sicurezza — solo un normale pacchetto npm che esporta una factory di descrittori più createPlugin. Gli operatori del sito lo installano con npm install e lo registrano in astro.config.mjs.

Struttura del pacchetto

Un tipico pacchetto di plugin nativo:

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

Ometti le esportazioni ./admin e ./astro se il tuo plugin non ne ha bisogno.

Configurazione di build

I plugin nativi vengono distribuiti come moduli ES. La maggior parte degli autori usa tsdown (o tsup) con TypeScript. Esternalizza react, emdash e @emdash-cms/admin in modo che non vengano impacchettati nell’output:

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

Se distribuisci componenti Astro per il rendering Portable Text, questi non necessitano di impacchettamento — Astro consuma direttamente i file sorgente .astro. Elenca la directory astro/ sotto files in modo che siano inclusi nel tarball npm.

Versioning

Usa il versioning semantico. Incrementare una versione principale è un segnale agli operatori che potrebbero dover apportare modifiche durante l’aggiornamento. La forma di definePlugin() e l’API del contesto del plugin sono stabili, ma se modifichi il comportamento degli hook del tuo plugin, i requisiti di capability o lo schema delle impostazioni in un modo che influisce sulle installazioni esistenti, quella è una breaking change.

Le capability sono parte del contratto di superficie del plugin. Aggiungerne una in una release non principale significa che gli operatori esistenti aggiornano e concedono silenziosamente una nuova capability — questo va bene per un plugin sandbox dove il dialogo di consenso si ripresenta, ma i plugin nativi non hanno un flusso di consenso. Tratta le aggiunte di capability come un bump di versione principale per i plugin nativi, oppure documentale in modo molto prominente nelle note di rilascio.

README e documentazione

Un buon README di plugin copre:

• Cosa fa il plugin, in una frase.
• Come installarlo (npm install ... e lo snippet di astro.config.mjs con l’import).
• Quali capability dichiara e per cosa le usa.
• Eventuali modifiche richieste al template Astro (ad es. <EmDashHead /> per page:metadata, <EmDashBodyEnd /> per page:fragments).
• Impostazioni e cosa controlla ciascuna.
• Note di migrazione tra versioni principali.

Pubblicare su npm

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

Per i pacchetti con scope, --access public è richiesto alla prima pubblicazione (npm imposta i pacchetti con scope come privati per impostazione predefinita).

Sviluppo locale contro un sito host

Quando si itera su un plugin, collegalo a un sito di test piuttosto che ripubblicare ad ogni modifica:

# 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

Quindi registra il plugin nell’astro.config.mjs del sito di test ed esegui il server di sviluppo. Gli handler degli hook vengono eseguiti alla richiesta successiva dopo il completamento di pnpm build.

Marketplace? No.

I plugin nativi non possono essere pubblicati sul marketplace EmDash. Il marketplace è solo per sandbox: ogni plugin pubblicato passa attraverso emdash plugin bundle (che valida che il codice backend sia autocontenuto, non importi moduli integrati di Node.js e rimanga entro i limiti di dimensione), riceve un audit di sicurezza e viene eseguito nel runtime sandbox quando installato.

Se desideri la superficie di distribuzione del marketplace ma il tuo plugin attualmente utilizza funzionalità esclusive dei nativi, chiediti se ne hai davvero bisogno — molti plugin possono eliminare page:fragments o convertire da settingsSchema a una pagina di impostazioni Block Kit e diventare sandboxabili. Vedi Scegliere un formato di plugin per i compromessi.