Upgrade auf Ardo 6

Ardo 6 baut statische Websites nur mit Vite. react-router und @react-router/dev entfallen; es gibt keinen Clientrouter. Jede Seite wird beim Build zu HTML. Links laden das nächste vorgerenderte Dokument, das anschließend hydriert.

Die Migration entfernt vor allem Dateien. Routen unter app/routes/, Root-Komponente und Ardo-Konfiguration bleiben. Hintergründe stehen in ADR 0020. Bei bisherigem typedoc folge zusätzlich der TypeDoc-Migration.

So funktioniert der Build

• ardo build ruft Vites Builder-API im selben Prozess auf. Es baut Client und Server, rendert jede Route nach build/client/<route>/index.html und bei gesetztem versioning in einen Versionsordner wie build/client/v6/, schreibt 404.html und prüft alle internen Links und Anker im fertigen HTML.
• ardo dev nutzt Vite mit Ardos Serverrendering-Middleware und liefert dasselbe Dokument wie der Build.
• ardo preview dient als statischer Host: /guide liefert guide/index.html; unbekannte Pfade erhalten die nächste 404.html.

Nutze diese drei Befehle weiter. react-router build und react-router dev entfallen.

Entfallene Dateien löschen

Lösche diese Dateien; ihre Aufgaben übernimmt Ardo:

Entferne auch react-router, @react-router/dev, @react-router/node und isbot aus package.json, falls das Projekt sie deklariert. Ardo verwaltet React, React DOM und Vite selbst. Wenn tsconfig.json den Eintrag .react-router/types unter include oder rootDirs enthält, entferne ihn.

Verschiebe Provider in die Root-Komponente und Dokumentmarkup in Layout (siehe unten). Für anfragespezifischen Serverkontext exportiere withRenderContext aus app/server.ts. Internationalisierung zeigt isolierte gleichzeitige Palamedes-Renderings.

Inhaltsicons aktualisieren

ardo/icons exportiert eine Auswahl Streamline Core Line statt einer ganzen Bibliothek. Der Katalog zeigt alle 50 Core-Exporte. Marken wie Github bleiben.

Alle 50 Icons sind automatisch registriert. Entferne ihre Imports und registerIcons() aus app/root.tsx; behalte nur eigene Registrierungen. Ersetze Code2 durch Code, auch in <Icon name="Code" /> und <Card icon="Code">.

Die Komponenten akzeptieren size, className und SVG-Attribute. Entferne die alte Iconabhängigkeit, wenn ungenutzt. Weitere Bibliotheken installierst und registrierst du explizit. Der Katalog beschreibt Motive und Nutzungsbedingungen.

app/root.tsx aktualisieren

Der Standardexport bleibt die Root-Komponente. <ArdoRoot> liest Konfiguration und generiert die Seitenleiste selbst. config-Prop, virtual:ardo/config und ardo/ui/styles.css können weg. Drei optionale Exporte bleiben:

• meta: als ArdoMetaFunction aus ardo/runtime typisiert. Es nimmt keine Argumente und liefert die bisherigen Deskriptoren, etwa { title: "My Docs" }. Entferne den Export, wenn er nur den Website-Titel setzte: Seiten ohne title erhalten ihren Titel aus ardo.config.ts.
• Layout: die HTML-Hülle, die jetzt nur auf dem Server rendert. Ohne Export nutzt Ardo ArdoRootLayout aus ardo/ui; die meisten Projekte können ihren Layout-Export löschen.
• ErrorBoundary: bei fehlenden Seiten innerhalb der Root, bei Renderfehlern anstelle der Root. Standard ist ArdoErrorBoundary.

Vorher:

import type { ReactNode } from "ardo/react"
import type { MetaFunction } from "ardo/router"
import { ArdoFooter, ArdoHeader, ArdoRoot, ArdoRootLayout, ArdoSidebar } from "ardo/ui"
import config from "virtual:ardo/config"
import "ardo/ui/styles.css"

export const meta: MetaFunction = () => [{ title: "My Docs" }]

export function Layout({ children }: { children: ReactNode }) {
  return <ArdoRootLayout>{children}</ArdoRootLayout>
}

export default function Root() {
  return (
    <ArdoRoot config={config}>
      <ArdoHeader />
      <ArdoSidebar />
      <ArdoFooter />
    </ArdoRoot>
  )
}

Nachher:

import { ArdoRoot } from "ardo/ui"

export default function Root() {
  return <ArdoRoot />
}

Behalte ArdoHeader, ArdoSidebar oder ArdoFooter als Kinder bei eigenen Props. Ohne Kinder rendert ArdoRoot dieselben Standardteile.

Behalte Layout, wenn es Optionen wie colorScheme, icon oder className an ArdoRootLayout übergibt. Die Ardo-5-Props theme und favicon heißen jetzt colorScheme und icon. Eigene Hüllen ersetzen React Routers <Meta />, <Links /> und <Scripts /> durch <ArdoHead /> in <head> und <ArdoScripts /> am Ende von <body>, beide aus ardo/runtime. Siehe Layout und Navigation.

Routen behalten meta und handle, etwa export const handle = { layout: "bare" }.

Theme nach app/root.tsx verschieben

Ardo 6 gestaltet die Website in JSX. brand entfällt in der Konfiguration, ebenso applyBrandTheme und createTheme aus ardo/theme. Farben, chroma und Tokens gehören in ArdoRoot-theme, Logos und Favicons werden importierte Dateien mit Vite-Fingerprints. Verbliebenes brand erzeugt einen Fehler mit Verweis hierher.

Vorher:

// ardo.config.ts
export default defineArdoConfig({
  title: "My Docs",
  brand: { color: "blue", accent: "teal", neutral: "slate", logo: "./app/assets/logo.svg" },
  icons: { source: "./app/assets/icon.svg" },
})

// app/styles/brand.css.ts
applyBrandTheme({ primary: 240, chroma: { brand: 0.6 }, dark: { color: { bg: "#101010" } } })

Nachher:

// app/root.tsx
import { ArdoRoot } from "ardo/ui"

import icon from "./assets/icon.svg"
import logo from "./assets/logo.svg"

export default function Root() {
  return (
    <ArdoRoot
      theme={{
        color: "blue",
        accent: "teal",
        neutral: "slate",
        chroma: { color: 0.6 },
        dark: { color: { bg: "#101010" } },
      }}
      logo={logo}
      icon={icon}
    />
  )
}

• primary und secondary aus applyBrandTheme werden color und accent; der Chroma-Schlüssel brand wird color.
• Gemeinsame Tokenüberschreibungen gehören in tokens, Farben meist in light und dark.
• icons.source entfällt. Ohne icon bleiben Eulenicons; icons: false deaktiviert sie weiterhin.
• gray und slate sind jetzt Grau und gedämpftes Blau statt des gesättigten Blaus aus Ardo 5.
• Die ungenutzten Variablen --ardo-color-brandLight, accentLight, accentDark, accentSubtle, bgAlt und sidebarBorder entfallen.
• --ardo-font-familyHeading folgt --ardo-font-family; neue Textschriften gelten auch für Überschriften.

Theming beschreibt alle Props.

tsconfig.json vereinfachen

Ersetze die Compileroptionen durch Ardos Preset. Es setzt jsx, jsxImportSource: "ardo", moduleResolution: "bundler", strikten Modus und Ardos Typdeklarationen:

{
  "extends": "ardo/tsconfig",
  "include": ["app/**/*", "*.ts"]
}

Router-Imports ersetzen

Importiere Runtime-Werte aus ardo/runtime oder ardo/ui. Der Paket-Einstieg ardo enthält auch Node-Code und gehört nicht in Browsercode. React-APIs kommen weiterhin aus ardo/react, und die Unterpfade von ardo/react-dom/* bleiben erhalten.

Außer ArdoMetaFunction und ArdoMetaDescriptor sind dies Werte aus ardo/runtime. ArdoLink und ArdoActiveLink gibt es auch in ardo/ui. Props mit React-Routers To akzeptieren jetzt string.

ArdoLink ergänzt den Basispfad und rendert <a>:

import { ArdoLink, useArdoPath } from "ardo/runtime"

export function BackToGuide() {
  const path = useArdoPath()
  if (path.startsWith("/guide")) return null
  return <ArdoLink to="/guide/getting-started">Read the guide</ArdoLink>
}

In Tests und Vorschauen umschließt ArdoPageProvider Komponenten mit Seitenzugriff:

import { ArdoPageProvider } from "ardo/runtime"

render(
  <ArdoPageProvider path="/guide/intro">
    <ComponentUnderTest />
  </ArdoPageProvider>
)

Basispfad einmal konfigurieren

Ein separates Router-basename und der Flatten-Schritt entfallen. Setze den Basispfad in Ardos Konfiguration; er gilt für Assets, Links und Ausgabeordner:

• GitHub-Pages-Projekte: base: "/repo/".
• Root-Deployments und eigene Domains: keine Angabe.
• Versionierte Dokumentation: versioning; Seiten etwa unter build/client/v6/, globale Dateien wie versions.json unter build/client/.

Vollständige Beispiele unter Deployment.

Routen-Loader ersetzen

loader und action werden nicht unterstützt. Vorgerenderte Seiten brauchen ihre Daten beim Build. Liefere sie über ein kleines Vite-Plugin mit virtuellem Modul:

// vite.config.ts
import { defineConfig, type Plugin } from "ardo/vite"

function releaseFacts(): Plugin {
  const id = "virtual:docs/release-facts"
  return {
    name: "docs:release-facts",
    resolveId(source) {
      return source === id ? `\0${id}` : undefined
    },
    async load(source) {
      if (source !== `\0${id}`) return undefined
      const response = await fetch("https://registry.npmjs.org/ardo/latest")
      const { version } = await response.json()
      return `export default ${JSON.stringify({ version })}`
    },
  }
}

export default defineConfig({
  plugins: [releaseFacts()],
})

// app/routes/releases.tsx
import facts from "virtual:docs/release-facts"

export default function Releases() {
  return <p>Latest release: {facts.version}</p>
}

Deklariere das Modul in .d.ts. Ardos npm-Statistik auf der Startseite nutzt dieses Muster. Server und hydrierender Client importieren so dieselben Daten.

Verhaltensänderungen

• Frontmatter-layout ist bare oder default. doc, home und page hatten keine Wirkung auf die Darstellung und erzeugen jetzt eine Warnung über ungültige Werte.
• Jede Seite hat einen Titel. Wenn weder Seitenmodul noch Root ein title-Metadatum setzen, erhält die Seite den Website-Titel aus ardo.config.ts.
• Keine GitHub-Remote-Erkennung. Ardo 5 verwendete den Repository-Namen als Basispfad, sofern githubPages: false nicht gesetzt war. Ardo 6 entfernt githubPages und detectGitHubBasename. Setze base für Unterpfade; es gilt in Entwicklung und Build.
• Volle Seitennavigation. Jeder Link ist <a> und lädt ein neues Dokument. Clientzustand wie offene Suche bleibt nicht erhalten.
• Abschließende Schrägstriche. Ardo erzeugt interne Seitenlinks mit einem abschließenden Schrägstrich, etwa /guide/intro/, damit statische Hoster die index.html jeder Seite ohne Weiterleitung ausliefern. Dateilinks wie llms.txt behalten ihre Form.
• Linkprüfung im fertigen HTML. ardo build prüft jeden internen Link, jedes Bild, Skript, Stylesheet und #fragment im erzeugten HTML, auch aus Komponenten und generierten Seiten, sowie Weiterleitungsziele und Versionsdateien. Konfiguriere die Prüfung mit linkCheck.
• Verzögerte Suche. Der Suchindex lädt beim ersten Suchfokus, pro Sprache getrennt.

Performance

Historischer Vergleich der rein englischen Ardo-Dokumentation vor dem viersprachigen Beispiel, M1 Ultra, warmer Build:

Früh geladenes JavaScript über alle damaligen Seiten sank von etwa 425 KB auf 379 KB gzip. Der verzögerte Suchindex ist darin nicht enthalten.

Upgrade prüfen

Führe Typprüfung, Tests und ardo build aus. Der Build darf keine defekten internen Links melden. Öffne mit ardo preview mehrere Seiten, folge Links und prüfe die Browserkonsole auf Fehler.