Distribuzione di plugin nativi

I plugin nativi si distribuiscono tramite npm. Un plugin nativo è un normale pacchetto npm che esporta una factory di descriptor 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 ha la seguente struttura:

@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

Il seguente package.json dichiara gli script di build, gli export e le peer dependencies di cui un plugin distribuibile ha bisogno:

{
	"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 gli export ./admin e ./astro se il tuo plugin non ne ha bisogno.

Configurazione del 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 inclusi nel tuo 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 di Portable Text, questi non necessitano di bundling — Astro consuma direttamente i file sorgente .astro. Elenca la directory astro/ sotto files in modo che siano inclusi nel tarball npm.

Versionamento

Usa il versionamento semantico. Incrementare una versione major è 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 dell’hook del tuo plugin, i requisiti di capacità o lo schema delle impostazioni in un modo che influisce sulle installazioni esistenti, questo è un cambiamento incompatibile.

Le capacità fanno parte del contratto di superficie del plugin. Aggiungerne una in una release non major significa che gli operatori esistenti aggiornano e concedono silenziosamente una nuova capacità — va bene per un plugin sandboxed dove la finestra di dialogo del consenso richiede nuovamente, ma i plugin nativi non hanno un flusso di consenso. Tratta le aggiunte di capacità come un incremento di versione major per i plugin nativi, o documentale molto prominentemente 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 astro.config.mjs con l’import).
• Quali capacità dichiara e per cosa le usa.
• Eventuali modifiche richieste al template Astro (es. <EmDashHead /> per page:metadata, <EmDashBodyEnd /> per page:fragments).
• Impostazioni e cosa controlla ciascuna.
• Note di migrazione tra le versioni major.

Pubblicazione su npm

Incrementa la versione e pubblica il pacchetto:

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

Per i pacchetti scoped, --access public è richiesto alla prima pubblicazione (npm imposta i pacchetti scoped 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 ripubblicarlo 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 prossima richiesta dopo che pnpm build è terminato.

Disponibilità sul marketplace

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 autonomo, non importi built-in di Node.js e rimanga sotto i limiti di dimensione), ottiene un audit di sicurezza e viene eseguito nel runtime sandbox quando installato.

Un plugin che usa funzionalità esclusive native può talvolta eliminarle e diventare sandboxable — ad esempio, rimuovendo page:fragments o convertendo settingsSchema in una pagina di impostazioni Block Kit. Vedi Scegliere un formato di plugin per i compromessi.