Plugins

Installation

npm install @nera-static/plugin-navigation

Jede Abhängigkeit, deren Name mit @nera-static/plugin- beginnt, wird automatisch entdeckt und angewendet — kein Registrierungsschritt. (@nera-static/plugin-utils ist eine Hilfsbibliothek, kein Plugin, und wird übersprungen.)

Ein Plugin nur für eine Website braucht kein Paket: Lege es unter src/plugins/<name>/index.js ab oder bestimme mit folders.plugins in config/app.yaml einen anderen Ordner. Siehe Schreibe dein eigenes lokales Plugin.

Der Hook-Vertrag

Ein Plugin ist ein ESM-Modul, das bis zu drei Hooks exportiert, getAppData, getMetaData und getAssets (unten):

export function getAppData({ app, pagesData }) {
    return { ...app, myKey: 'value' }   // must return a plain object
}

export function getMetaData({ app, pagesData }) {
    return pagesData                    // must return an array
}

getAppData läuft zuerst; getMetaData sieht das app, das es zurückgegeben hat. Core wartet auf jeden Hook (seit Core 4.3.0; ältere Versionen ersetzten app stillschweigend durch ein Promise), aber synchron bleibt die sichere Wahl — so machen es auch die veröffentlichten Plugins.

Ein Plugin, das Dateien erzeugt (zum Beispiel generierte Bilder), exportiert zusätzlich getAssets (Core ≥ 4.13.0). Der Hook läuft nach getAppData und getMetaData aller Plugins, sieht das endgültige app und pagesData und gibt zurück, was nach public/ kopiert werden soll:

export function getAssets({ app, pagesData }) {
    return [{ from: '/abs/path/to/files', to: '_img' }]
}

from ist eine absolute Datei oder ein absoluter Ordner, to ein Pfad innerhalb von public/. Core kopiert diese Einträge nach den Assets des Themes und vor deinen eigenen, sodass dein theme/assets/ bei gleichen Namen weiterhin gewinnt. Ungültige Einträge werden mit einer Warnung übersprungen.

Die Konfiguration liegt in deinem Projekt

Jedes Plugin liest config/<name>.yaml aus deiner Site, nicht aus dem Paket. Das im Paket mitgelieferte YAML ist Dokumentation; kopiere es in dein config/ und bearbeite es. Fehlende Schlüssel fallen auf sinnvolle Standardwerte zurück.

Reihenfolge

config/plugin-order.yaml steuert die Ausführungsreihenfolge: Namen unter start: laufen zuerst, dann alles Übrige alphabetisch, dann Namen unter end:. Die Suche läuft zuletzt, damit sie die endgültigen Seitendaten indexiert.

Templates

Plugins, die Views mitliefern, stellen einen Publish-Befehl bereit:

npx nera-navigation      # copies templates into theme/views/vendor/plugin-navigation/

include sie dann aus deinen Layouts. Das Veröffentlichen wird übersprungen, wenn der Ordner bereits existiert — lösche ihn (oder übergib --force), um Template-Updates einzuspielen.