Actualizar a Ardo 6

Ardo 6 construye sitios estáticos solo con Vite. Desaparecen react-router y @react-router/dev, sin router cliente. Cada página se renderiza a HTML durante el build. Los enlaces cargan el siguiente documento prerrenderizado, que después se hidrata.

La migración elimina sobre todo archivos. Las rutas app/routes/, el componente raíz y la configuración se conservan. Consulta ADR 0020. Si usabas typedoc, sigue también Migrar desde TypeDoc.

Cómo funciona el build

• ardo build llama al builder de Vite en el mismo proceso. Construye cliente y servidor, prerrenderiza cada ruta en build/client/<route>/index.html, bajo una carpeta de versión como build/client/v6/ si se configura versioning, escribe 404.html y comprueba los enlaces y anclas internos del HTML final.
• ardo dev usa Vite con el middleware de render de Ardo y sirve el mismo documento que el build.
• ardo preview funciona como alojamiento estático: /guide sirve guide/index.html; las rutas desconocidas reciben el 404.html más cercano.

Mantén estos tres comandos. Desaparecen react-router build y react-router dev.

Eliminar los archivos retirados

Elimina estos archivos; Ardo asume sus funciones:

Quita también react-router, @react-router/dev, @react-router/node y isbot de package.json si el proyecto los declara. Ardo gestiona React, React DOM y Vite. Si tsconfig.json incluye .react-router/types en include o rootDirs, elimínalo.

Mueve los providers a la raíz y el documento a Layout (más abajo). Para contexto servidor por solicitud, exporta withRenderContext desde app/server.ts. Internacionalización muestra el aislamiento de renders concurrentes con Palamedes.

Actualizar los iconos

ardo/icons exporta una selección Streamline Core Line en lugar de una biblioteca entera. El catálogo enumera los 50 exports Core. Las marcas como Github permanecen.

Los 50 iconos se registran automáticamente. Quita sus imports y registerIcons() de app/root.tsx, salvo registros propios. Reemplaza Code2 por Code, también en <Icon name="Code" /> y <Card icon="Code">.

Los componentes aceptan size, className y atributos SVG. Quita la dependencia antigua si no se usa. Instala y registra explícitamente otras bibliotecas. El catálogo detalla motivos y condiciones.

Actualizarapp/root.tsx

El export predeterminado sigue siendo la raíz. <ArdoRoot> lee la configuración y genera la navegación. Quita la prop config, virtual:ardo/config y ardo/ui/styles.css. Quedan tres exports opcionales:

• meta: tipado como ArdoMetaFunction desde ardo/runtime, sin argumentos, devuelve los mismos descriptores de antes, como { title: "My Docs" }. Elimínalo si solo definía el título del sitio: las páginas sin title reciben el título de ardo.config.ts.
• Layout: el shell HTML, que ahora solo se renderiza en el servidor. Si lo omites, Ardo usa ArdoRootLayout de ardo/ui; la mayoría de proyectos pueden eliminar su export Layout.
• ErrorBoundary: dentro de la raíz para páginas ausentes, en su lugar para errores de render. Predeterminado: ArdoErrorBoundary.

Antes:

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

Después:

import { ArdoRoot } from "ardo/ui"

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

Mantén ArdoHeader, ArdoSidebar o ArdoFooter como hijos si tienen props propias. Sin hijos, ArdoRoot renderiza los mismos elementos predeterminados.

Mantén Layout si pasa opciones como colorScheme, icon o className a ArdoRootLayout. Las props de Ardo 5 theme y favicon pasan a colorScheme y icon. Un shell propio reemplaza <Meta />, <Links /> y <Scripts /> de React Router por <ArdoHead /> en <head> y <ArdoScripts /> al final de <body>, ambos desde ardo/runtime. Consulta Diseño y navegación.

Las rutas conservan meta y handle, por ejemplo export const handle = { layout: "bare" }.

Mover el tema aapp/root.tsx

Ardo 6 define el tema en JSX. Desaparece brand de la configuración, junto con applyBrandTheme y createTheme de ardo/theme. Tonos, chroma y tokens van en theme de ArdoRoot; logotipos y favicons son imports con huellas de Vite. Un brand antiguo produce un error con enlace a esta guía.

Antes:

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

Despué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 y secondary de applyBrandTheme pasan a color y accent; la clave chroma brand pasa a color.
• Los tokens comunes van en tokens y los colores normalmente en light y dark.
• Desaparece icons.source. Sin icon permanecen los iconos de búho; icons: false sigue desactivándolos.
• gray y slate son gris y azul apagado en vez del azul saturado de Ardo 5.
• Desaparecen las variables sin uso --ardo-color-brandLight, accentLight, accentDark, accentSubtle, bgAlt y sidebarBorder.
• --ardo-font-familyHeading sigue a --ardo-font-family: la fuente de texto también llega a los títulos.

Temas detalla las props.

Simplificartsconfig.json

Reemplaza las opciones del compilador por el preajuste de Ardo. Define jsx, jsxImportSource: "ardo", moduleResolution: "bundler", el modo estricto y las declaraciones de tipos de Ardo:

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

Reemplazar imports del router

Importa valores de ejecución desde ardo/runtime o ardo/ui. La entrada ardo también contiene código Node y no debe usarse en el navegador. Las API React siguen en ardo/react y se conservan las subrutas de ardo/react-dom/*.

Salvo ArdoMetaFunction y ArdoMetaDescriptor, son valores de ardo/runtime. ArdoLink y ArdoActiveLink también están en ardo/ui. Las props que usaban To ahora aceptan string.

ArdoLink añade la base y renderiza 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>
}

En pruebas y vistas previas, envuelve los componentes que leen la página con ArdoPageProvider:

import { ArdoPageProvider } from "ardo/runtime"

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

Configurar la base una sola vez

Ya no hay un basename separado del router ni un paso de aplanado. Define la ruta base en Ardo; se aplica a recursos, enlaces y directorios de salida:

• Proyectos GitHub Pages: base: "/repo/".
• Raíz y dominios propios: sin ajuste.
• Documentación versionada: versioning, páginas bajo build/client/v6/ y archivos globales como versions.json bajo build/client/.

Ejemplos completos en Despliegue.

Reemplazar loaders

No se admiten loader ni action. Las páginas prerrenderizadas necesitan sus datos durante el build. Proporciónalos con un pequeño plugin Vite y un módulo virtual:

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

Declara el módulo en un .d.ts. Las estadísticas npm del inicio siguen este patrón. Servidor y cliente de hidratación importan así los mismos datos.

Cambios de comportamiento

• El layout del frontmatter es bare o default. doc, home y page nunca cambiaron el renderizado y ahora generan un aviso de valor no válido.
• Cada página tiene un título. Si ni su módulo ni la raíz definen el metadato title, la página recibe el título del sitio desde ardo.config.ts.
• Sin detección del remoto GitHub. Ardo 5 usaba el nombre del repositorio como base salvo que se configurara githubPages: false. Ardo 6 elimina githubPages y detectGitHubBasename. Define base para subrutas, tanto en desarrollo como en build.
• Navegación completa. Cada <a> carga un documento nuevo. Se pierde el estado cliente, como una búsqueda abierta.
• Barras finales. Ardo termina los enlaces internos con una barra, como /guide/intro/, para que el alojamiento estático sirva el index.html de cada página sin redirecciones. Los enlaces a archivos como llms.txt conservan su forma.
• Comprobación de enlaces del HTML final. ardo build comprueba cada enlace interno, imagen, script, hoja de estilo y #fragment del HTML generado, incluidos componentes, páginas generadas, destinos de redirección y archivos de versión. Configúrala con linkCheck.
• Búsqueda diferida. El índice se carga al primer foco de búsqueda, por separado para cada idioma.

Rendimiento

Referencia histórica del sitio inglés antes del ejemplo en cuatro idiomas, M1 Ultra, build en caliente:

El JavaScript inicial del conjunto de páginas de entonces pasó de unos 425 a 379 KB gzip. No incluye el índice diferido.

Verificar la actualización

Ejecuta comprobación de tipos, pruebas y ardo build. No debe haber enlaces internos rotos. Con ardo preview, abre varias páginas, sigue enlaces y comprueba la consola.