Veröffentlichen

Wie eine Ginko-Seite online geht. Vercel mit ISR, ein statischer Build für Seiten aus Dateien, die Umgebungsvariablen und was ein statischer Host nicht kann.

Zwei Arten von Seiten

Wie du veröffentlichst, hängt davon ab, woher die Inhalte kommen:

Nur Dateien. Jeder Baustein hat source: 'files'. Die Inhalte stehen beim Build fest. Du kannst mit nuxt generate eine statische Seite bauen und auf jeden statischen Host legen, oder sie wie jede Nuxt-Seite auf Vercel bringen.
Plattform. Mindestens ein Baustein kommt von der Plattform. Inhaber ändern Inhalte nach dem Deploy, also braucht die Seite einen Server, der neue Inhalte holt. Ginko ist für Vercel gemacht und dort getestet.

Lass vor dem Deploy ginko check in der CI laufen. Es prüft die Konfiguration, die Inhaltsdateien und die Links und endet bei einem Fehler mit Code 1. Siehe Plattform und CLI.

Vercel

Importiere das Repository auf Vercel. Vercel erkennt Nuxt und führt nuxt build aus; an den Build-Einstellungen änderst du nichts.

Setz url in ginko.config.ts auf die Adresse der Produktion. Ginko markiert jeden anderen Host, etwa die Vorschau-Deployments von Vercel, mit noindex, damit Vorschauen nie in einer Suchmaschine landen (siehe SEO und Agenten).

Das Modul setzt diese Cache-Regeln für dich (Vercel ISR). Deine eigenen routeRules in nuxt.config.ts gewinnen: Ginko füllt nur, was du offen lässt. Die Ausnahme ist /__ginko/: Dort setzt Ginko immer die Cache-Regel und die Header cache-control und x-robots-tag, damit die Vorschau nie zwischengespeichert oder indexiert wird.

Jede Seite wird zwischengespeichert und höchstens alle 60 Sekunden neu gerendert. Query-Parameter teilen sich einen Cache-Eintrag. Die 60 Sekunden sind ein Standardwert, kein Versprechen: Mit einer eigenen Regel für /** (zum Beispiel routeRules: { '/**': { isr: 300 } }) behält Ginko deine. Eine Regel für einen engeren Pfad, etwa /news/**, gewinnt ohnehin.
/api/** wird nicht zwischengespeichert, weil deine eigenen Server-Routen von der Sprache des Besuchers abhängen können.
Ginkos eigene Adressen unter /__ginko/ werden nie indexiert. Was davon der Build erzeugt, der Suchindex /__ginko/search/<sprache>.json und die Inhalte der Datei-Bausteine unter /__ginko/files/, bleibt bis zum nächsten Deploy im Cache. Auf einer Seite mit Plattform-Bausteinen enthält der Suchindex auch Inhalte der Plattform, darum wird er wie eine Seite zwischengespeichert. Alles andere dort, etwa die Vorschau, wird nie zwischengespeichert. Welche Adressen stabil und welche intern sind: Adressen und Header.
Antwortet die Plattform nicht, antwortet die Seite mit 503, und Vercel behält die letzte gute Seite.
Der Cache hält eine Fassung pro Adresse und übergeht Vary. Eine Seite antwortet darum allen mit demselben HTML, und Agenten lesen ihr Markdown unter ihrer .md-Adresse. Auch ein Fehler wie eine fehlende Seite antwortet immer mit der Fehlerseite als HTML, selbst wenn zuerst curl oder ein Monitor ohne Accept: text/html fragt. Nur /api/, Adressen auf .json und /__ginko/ behalten Nuxts Wahl zwischen JSON und HTML.

Ginko schaltet außerdem experimental.payloadExtraction aus. Damit lädt Nuxt bei einer Navigation im Browser eine _payload.json, und der Server rendert dafür die Zielseite mit den Inhalten von production. Die Seiten lesen stattdessen die Inhalte, die schon im Browser sind. So zeigt die Vorschau nie Inhalte von production, und eine Navigation kostet kein zusätzliches Rendern.

Vorschaukarten

Eine Site mit Vorschaukarten (nuxt-og-image, in jedem Starter), die auf einem Server rendert, braucht NUXT_APP_SECRET: ein zufälliges Geheimnis mit mindestens 32 Zeichen. nuxt-og-image signiert damit die Adressen der Karten; ohne es antwortet jede Karte mit einem Fehler, und der Build warnt. create-ginko schreibt eines in .env für deinen Rechner; setz auch auf Vercel eines. Ein statischer Build (nuxt generate) zeichnet jede Karte beim Build und braucht keines.

Eine Plattform-Seite

Eine Seite mit Plattform-Bausteinen braucht diese Umgebungsvariablen auf Vercel. Setze beide für Production und Preview: Eine Variable, die nur für Preview existiert, lässt die Produktionsseite ohne Inhalte. Ein Production-Build auf Vercel ohne Plattform-Adresse bricht mit einem Fehler ab; ein Preview-Build warnt nur.

Variable	Wert
`NUXT_PUBLIC_GINKO_PLATFORM`	Die Adresse der Plattform. Nicht nötig, wenn die `ginko.config.ts` `platform` setzt; die Variable überschreibt es. Ohne beides antwortet jede Seite mit Inhalten von der Plattform mit 503, und das Server-Log sagt das einmal.
`NUXT_GINKO_REVALIDATE_TOKEN`	Das Website-Token: Erstelle es im Studio unter Team, „Website-Token“. Optional, siehe unten. Ein Build auf Vercel ohne ihn gibt eine Warnung aus.

Ohne NUXT_GINKO_REVALIDATE_TOKEN erreicht eine veröffentlichte Änderung die Seite innerhalb von 60 Sekunden. Ginko gibt das Token als bypassToken an Vercel, außer deine nuxt.config.ts setzt nitro.vercel.config.bypassToken selbst. Mit ihm rendert die Plattform die geänderten Seiten gleich nach dem Veröffentlichen neu, und Inhaber können „Website jetzt aktualisieren“ nutzen. Der Server der Seite schickt es auch beim Laden der Inhalte mit, so können Besucher das Anfragelimit der Seite nicht aufbrauchen. Erstelle das Token im Studio (Team, „Website-Token“, nur Inhaber): Die Plattform speichert es und zeigt es einmal an. Ein neues Token beendet das alte sofort; trage den neuen Wert dann gleich auf Vercel ein und deploye neu.

In der CI bringt ginko release ein neues Schema vor dem Deploy in die Produktion. Ein überholter Lauf ist kein Fehler: Er endet mit Exit-Code 0 und gibt "deploy":false aus. Veröffentliche darum nur, wenn es "deploy":true ausgibt. Die Seite Plattform und CLI hat ein CI-Beispiel und die Tabelle der Exit-Codes.

Suchmaschinen indexieren eine Seite nur unter der Adresse in ihrer url; jede andere Adresse bekommt noindex. Eine Demo, oder eine Seite, die bis zum Domain-Wechsel unter einer Vorschau-Adresse wie name.vercel.app läuft, setzt auf diesem Deployment NUXT_PUBLIC_GINKO_NOINDEX=true: Dann sperrt robots.txt alles, und jede Antwort sendet X-Robots-Tag: noindex. Entferne die Variable, sobald die Seite auf ihre eigene Domain umzieht.

Die Plattform wird von Lupinum betrieben und ist auf Einladung offen. Eine Seite, deren Bausteine alle aus Dateien kommen, braucht keine Plattform und keine dieser Variablen.

Statischer Build (nur Dateien)

Eine Seite, deren Bausteine alle aus Dateien kommen, lässt sich als reine Dateien bauen:

Terminal

npx nuxt generate

Die Ausgabe in .output/public enthält jede Seite in jeder Sprache, die Markdown-Fassung jedes Eintrags, /llms.txt, /llms-full.txt, /sitemap.xml, /robots.txt, den Suchindex und, bei einer Doku-Seite, die RSS-Feeds. Lade den Ordner auf einen beliebigen statischen Host. Ein kaputter Link oder eine Seite, die nicht rendert, stoppt den Build.

Ein statischer Host hat keinen Server. Darum geht dort Folgendes nicht:

Weiterleitungen mit Mustern. Genaue Pfade, aus redirectFrom und aus redirects, landen in der Ausgabe. Regeln mit :name oder * brauchen einen Server.
Der MCP-Zugang der Doku (/__ginko/docs-mcp).
noindex auf Vorschau-Hosts. Die statische robots.txt ist für die Adresse der Produktion geschrieben. Halte Vorschau-Deployments mit der Einstellung deines Hosts aus Suchmaschinen heraus.

Brauchst du etwas davon? Dann bring dieselbe Seite mit nuxt build auf Vercel.

Doku-Seiten

Eine Seite mit @lupinum/ginko-docs liest ihre Seiten aus Dateien, also gehen beide Wege: nuxt generate für einen statischen Host, oder Vercel für den MCP-Zugang und Weiterleitungen mit Mustern.

Die Ginko-Doku selbst veröffentlicht außerdem die shadcn-vue-Registry der Komponenten unter /r. Ihr Build (pnpm --filter @lupinum/ginko-components registry) schreibt die Links der Einträge aus url in sites/docs/ginko.config.ts. GINKO_REGISTRY_URL überschreibt diese Adresse, zum Beispiel http://localhost:3500/r für einen Test auf dem eigenen Rechner.