Passer à Ardo 6

Ardo 6 construit des sites statiques avec Vite seul. react-router et @react-router/dev disparaissent, sans routeur client. Chaque page est rendue en HTML au build. Un lien charge le document prérendu suivant, qui s’hydrate ensuite.

La migration retire surtout des fichiers. Routes app/routes/, composant racine et configuration restent. Voir ADR 0020. Si vous utilisiez typedoc, suivez aussi Migrer depuis TypeDoc.

Fonctionnement du build

• ardo build appelle le builder Vite dans le même processus. Il construit client et serveur, prérend chaque route dans build/client/<route>/index.html, sous un dossier de version tel build/client/v6/ lorsque versioning est défini, écrit 404.html et vérifie tous les liens et ancres internes du HTML final.
• ardo dev utilise Vite avec le middleware de rendu Ardo et sert le même document que le build.
• ardo preview agit comme un hébergeur statique : /guide sert guide/index.html; les chemins inconnus reçoivent le 404.html le plus proche.

Conservez ces trois commandes. react-router build et react-router dev disparaissent.

Supprimer les anciens fichiers

Supprimez ces fichiers ; Ardo reprend leur rôle :

Retirez aussi react-router, @react-router/dev, @react-router/node et isbot de package.json si le projet les déclare. Ardo gère React, React DOM et Vite. Si tsconfig.json contient .react-router/types dans include ou rootDirs, retirez-le.

Déplacez les providers dans la racine et le document dans Layout (ci-dessous). Pour un contexte serveur par requête, exportez withRenderContext depuis app/server.ts. Internationalisation montre l’isolation des rendus concurrents avec Palamedes.

Mettre à jour les icônes

ardo/icons exporte une sélection Streamline Core Line plutôt qu’une bibliothèque entière. Le catalogue liste les 50 exports Core. Les marques comme Github restent.

Les 50 icônes sont enregistrées automatiquement. Retirez leurs imports et registerIcons() d’app/root.tsx, sauf pour les ajouts personnalisés. Remplacez Code2 par Code, y compris <Icon name="Code" /> et <Card icon="Code">.

Les composants acceptent size, className et les attributs SVG. Retirez l’ancienne dépendance si elle est inutilisée. Installez et enregistrez explicitement les autres bibliothèques. Le catalogue détaille motifs et conditions.

Mettre à jourapp/root.tsx

L’export par défaut reste la racine. <ArdoRoot> lit la configuration et génère la navigation. Retirez la prop config, virtual:ardo/config et ardo/ui/styles.css. Trois exports facultatifs restent :

• meta : typé ArdoMetaFunction depuis ardo/runtime, sans argument, renvoie les mêmes descripteurs qu’avant, tels { title: "My Docs" }. Retirez-le s’il ne définissait que le titre du site : les pages sans title reçoivent le titre de ardo.config.ts.
• Layout : le shell HTML, désormais rendu seulement sur le serveur. Sans cet export, Ardo utilise ArdoRootLayout de ardo/ui ; la plupart des projets peuvent supprimer leur export Layout.
• ErrorBoundary: dans la racine pour une page absente, à sa place pour une erreur de rendu. Défaut : ArdoErrorBoundary.

Avant :

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>
  )
}

Après :

import { ArdoRoot } from "ardo/ui"

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

Gardez ArdoHeader, ArdoSidebar ou ArdoFooter comme enfants s’ils ont des props personnalisées. Sans enfants, ArdoRoot rend les mêmes éléments par défaut.

Gardez Layout s’il passe des options comme colorScheme, icon ou className à ArdoRootLayout. Les props Ardo 5 theme et favicon deviennent colorScheme et icon. Un shell personnalisé remplace <Meta />, <Links /> et <Scripts /> de React Router par <ArdoHead /> dans <head> et <ArdoScripts /> en fin de <body>, tous deux depuis ardo/runtime. Voir Mise en page et navigation.

Les routes conservent meta et handle, par exemple export const handle = { layout: "bare" }.

Déplacer le thème dansapp/root.tsx

Ardo 6 définit le thème en JSX. brand disparaît de la configuration, ainsi qu’applyBrandTheme et createTheme d’ardo/theme. Teintes, chroma et tokens vont dans theme d’ArdoRoot; logos et favicons deviennent des imports avec fingerprints Vite. Un ancien brand déclenche une erreur vers ce guide.

Avant :

// 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" } } })

Après :

// 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 et secondary d’applyBrandTheme deviennent color et accent; la clé chroma brand devient color.
• Les tokens communs vont dans tokens, les couleurs généralement dans light et dark.
• icons.source disparaît. Sans icon, les icônes de chouette restent ; icons: false les désactive toujours.
• gray et slate sont gris et bleu atténué, au lieu du bleu saturé d’Ardo 5.
• Les variables inutilisées --ardo-color-brandLight, accentLight, accentDark, accentSubtle, bgAlt, sidebarBorder disparaissent.
• --ardo-font-familyHeading suit --ardo-font-family: la police de texte atteint aussi les titres.

Thèmes détaille les props.

Simplifiertsconfig.json

Remplacez les options du compilateur par le préréglage Ardo. Il définit jsx, jsxImportSource: "ardo", moduleResolution: "bundler", le mode strict et les déclarations de types Ardo :

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

Remplacer les imports du routeur

Importez les valeurs d’exécution depuis ardo/runtime ou ardo/ui. L’entrée ardo contient aussi du code Node et ne convient pas au navigateur. Les API React viennent toujours de ardo/react et les sous-chemins ardo/react-dom/* existent encore.

Hormis ArdoMetaFunction et ArdoMetaDescriptor, ce sont des valeurs d’ardo/runtime. ArdoLink et ArdoActiveLink existent aussi dans ardo/ui. Les props utilisant To acceptent désormais string.

ArdoLink ajoute la base et rend un <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>
}

Dans les tests et aperçus, entourez les composants lisant la page avec ArdoPageProvider:

import { ArdoPageProvider } from "ardo/runtime"

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

Configurer la base une seule fois

Il n’y a plus de basename séparé pour le routeur ni d’étape d’aplatissement. Définissez le chemin de base dans Ardo ; il s’applique aux ressources, liens et dossiers de sortie :

• Projets GitHub Pages : base: "/repo/".
• Racine et domaines personnalisés : rien à définir.
• Documentation versionnée : versioning, pages sous build/client/v6/ et fichiers globaux comme versions.json sous build/client/.

Exemples complets dans Déploiement.

Remplacer les loaders

loader et action ne sont pas pris en charge. Les pages prérendues ont besoin de leurs données au build. Fournissez-les via un petit plugin Vite avec module virtuel :

// 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>
}

Déclarez le module dans un .d.ts. Les statistiques npm de l’accueil suivent ce modèle. Serveur et client d’hydratation importent ainsi les mêmes données.

Changements de comportement

• Le layout du frontmatter vaut bare ou default. doc, home et page n’ont jamais modifié le rendu et produisent désormais un avertissement de valeur invalide.
• Chaque page possède un titre. Si ni son module ni la racine ne définissent la métadonnée title, la page reçoit le titre du site depuis ardo.config.ts.
• Plus de détection du remote GitHub. Ardo 5 utilisait le nom du dépôt comme base sauf si githubPages: false était défini. Ardo 6 supprime githubPages et detectGitHubBasename. Définissez base pour les sous-chemins, en développement comme au build.
• Navigation complète. Chaque <a> charge un document neuf. L’état client, telle une recherche ouverte, est perdu.
• Barres obliques finales. Ardo termine les liens internes par une barre oblique, comme /guide/intro/, pour que les hébergeurs servent le index.html de chaque page sans redirection. Les liens de fichiers tels llms.txt conservent leur forme.
• Vérification des liens du HTML final. ardo build vérifie chaque lien interne, image, script, feuille de style et #fragment du HTML généré, y compris les composants, pages générées, destinations de redirection et fichiers de version. Réglez-la avec linkCheck.
• Recherche différée. L’index charge au premier focus de recherche, séparément par langue.

Performances

Référence historique du site anglais avant l’exemple quadrilingue, M1 Ultra, build à chaud :

Le JavaScript chargé immédiatement sur l’ensemble des pages d’alors est passé d’environ 425 à 379 Ko gzip. L’index différé n’est pas inclus.

Vérifier la migration

Exécutez vérification des types, tests et ardo build. Aucun lien interne cassé ne doit être signalé. Avec ardo preview, ouvrez plusieurs pages, suivez les liens et vérifiez la console.