Actualizar a Astro v7

Esta guía te ayudará a migrar de Astro v6 a Astro v7.

¿Necesitas actualizar un proyecto anterior a v6 primero? Consulta nuestra guía de migración anterior.

¿Necesitas ver la documentación de v6? Visita esta versión anterior del sitio de documentación (snapshot v6 sin mantenimiento).

Actualizar Astro

Actualiza la versión de Astro de tu proyecto a la última versión usando tu gestor de paquetes:

# Upgrade Astro and official integrations together
npx @astrojs/upgrade

# Upgrade Astro and official integrations together
pnpm dlx @astrojs/upgrade

# Upgrade Astro and official integrations together
yarn dlx @astrojs/upgrade

También puedes actualizar tus integraciones de Astro manualmente si es necesario, y también podrías necesitar actualizar otras dependencias en tu proyecto.

Astro v7.0 incluye posibles cambios importantes, así como la remoción de algunas funcionalidades previamente deprecadas.

Si tu proyecto no funciona como se espera después de actualizar a v7.0, consulta esta guía para una descripción general de todos los cambios importantes e instrucciones sobre cómo actualizar tu código base.

Consulta el changelog de Astro para las notas de versión completas.

Cambios importantes

Actualizaciones de dependencias

Vite 8

Astro v7.0 actualiza a Vite 8 como servidor de desarrollo y bundler de producción.

¿Qué debo hacer?

Si estás usando plugins, configuración o APIs específicas de Vite, consulta la guía de migración de Vite 8 para sus cambios importantes y actualiza tu proyecto según sea necesario.

La mayoría de los usuarios de Astro deberían poder actualizar sin cambios en el código de su proyecto. Esto es principalmente un cambio importante para integraciones y plugins de Astro que dependen de los internos de Vite.

Flags experimentales

Los flags experimentales te permiten optar por funcionalidades mientras están en desarrollo temprano. Los siguientes flags experimentales han sido removidos en Astro 7.0 y ahora son estables, o el nuevo comportamiento por defecto.

Elimina estos flags experimentales de tu configuración de Astro si los estabas usando previamente:

import { defineConfig, logHandlers, memoryCache } from 'astro/config';

export default defineConfig({
  experimental: {
    logger: logHandlers.json({ pretty: true }),
    queuedRendering: {
      enabled: true,
    },
    rustCompiler: true,
    advancedRouting: true,
    cache: {
      provider: memoryCache(),
    },
    routeRules: {
      '/blog/[...path]': { maxAge: 300, swr: 60 },
    },
  },
  cache: {
    provider: memoryCache(),
  },
  routeRules: {
    '/blog/[...path]': { maxAge: 300, swr: 60 },
  },
})

Funcionalidades experimentales ahora estables:

logger: El nuevo sistema de logging ahora es estable y el flag experimental ya no es necesario para usarlo. Si estabas usando este flag, ahora puedes configurar tu logger directamente en el campo logger de nivel superior en tu configuración de Astro.
queuedRendering: El renderizado en cola es ahora el comportamiento por defecto, y el flag experimental ha sido removido. No se requiere ninguna acción para habilitar esta funcionalidad en tu proyecto. Todos los proyectos ahora se benefician del rendimiento mejorado.
rustCompiler: El compilador de Astro basado en Rust es ahora el compilador por defecto y único, reemplazando el compilador anterior basado en Go. Consulta Compilador de Rust para detalles sobre cambios de comportamiento que pueden afectar tu proyecto.
advancedRouting: El enrutamiento avanzado ahora está habilitado por defecto. Consulta la guía de enrutamiento avanzado para más información. Ten en cuenta que src/fetch.ts es ahora un nombre de archivo reservado.
cache: El caché de rutas ahora es estable. Si estabas usando esta funcionalidad, actualiza tu configuración para mover cache y routeRules fuera del bloque experimental.

Compilador de Rust

PR de implementación: feat!: make Rust compiler the default and only compiler (#16462)

Astro v7.0 reemplaza el compilador anterior basado en Go con un nuevo compilador basado en Rust. El nuevo compilador es más rápido, pero también es más estricto con la sintaxis HTML inválida. Las plantillas que previamente compilaban sin errores ahora pueden fallar.

El compilador de Rust aplica dos cambios clave:

Las etiquetas no cerradas ahora producen errores. El compilador anterior aceptaba silenciosamente etiquetas HTML y de componentes no cerradas. El compilador de Rust requiere que todos los elementos non-void tengan una etiqueta de cierre coincidente.
El HTML semánticamente inválido ya no se autocorrige. El compilador anterior reordenaría o reestructuraría silenciosamente el HTML inválido para coincidir con la especificación de parsing HTML (ej. mover elementos fuera de etiquetas <p> donde no se permiten elementos de bloque). El compilador de Rust no intenta corregir tu markup y en su lugar lo pasa tal cual, dejando que el navegador lo maneje. Esto puede causar una salida renderizada diferente para markup inválido previamente “tolerado”.

¿Qué debo hacer?

Ejecuta tu build después de actualizar. Si ves errores del compilador sobre tokens inesperados o etiquetas no cerradas, añade las etiquetas de cierre faltantes:

<!-- Before: unclosed tags that the Go compiler silently accepted -->
<p>Hello world
<p>Hello world</p>

<!-- Void elements like <br>, <img>, <input>, and <hr> do not need closing tags -->

---
import Layout from '../layouts/Layout.astro';
---
<Layout>
  <p>Content here

<Layout>
  <p>Content here</p>
</Layout>

Si tu salida HTML renderizada ha cambiado después de actualizar, inspecciona tus plantillas en busca de anidamiento HTML inválido que el compilador anterior corregía silenciosamente. Por ejemplo, colocar un <div> dentro de un <p> es HTML inválido. El compilador anterior reestructuraría esto por ti, pero el compilador de Rust no lo hará:

<!-- Invalid nesting: <div> is not allowed inside <p> -->
<!-- The browser will close the <p> early, which may break your layout -->
<p>
  <div>This will not be inside the paragraph</div>
</p>

<!-- Fix: use a valid container instead -->
<div>
  <div>This is correctly nested</div>
</div>

Diferencias en la salida de CSS

El compilador de Rust procesa el CSS de manera diferente, lo que puede causar diferencias visuales menores en tu salida compilada:

Los valores de color pueden serializarse de manera diferente. Los colores con nombre como rebeccapurple pueden convertirse en valores hex como #639 en el CSS compilado. Esto no cambia la apariencia visual de tu sitio.
Los valores url() pueden ganar o perder comillas. Por ejemplo, url(/path) puede convertirse en url('/path') o viceversa. Esto no afecta la funcionalidad.

Estas diferencias son cosméticas y no requieren ninguna acción a menos que tengas pruebas o herramientas que dependan de coincidencia exacta de strings CSS.

Nombre de archivo reservado: `src/fetch.ts`

Astro v7.0 introduce el enrutamiento avanzado, que usa src/fetch.ts (o src/fetch.js) como un nombre de archivo especial, similar a src/middleware.ts. Astro importará automáticamente este archivo para configurar el comportamiento del enrutamiento.

Si tu proyecto ya tiene un archivo src/fetch.ts usado para otros propósitos, Astro intentará procesarlo como una configuración de enrutamiento avanzado, lo que puede causar errores inesperados.

¿Qué debo hacer?

Si tienes un archivo src/fetch.ts existente que no está relacionado con el enrutamiento avanzado, tienes dos opciones:

Configurar fetchFile: puedes especificar un nombre de archivo diferente o null para deshabilitar el enrutamiento avanzado. Esto es útil si quieres seguir usando src/fetch.ts para otro propósito, o no necesitas las funcionalidades de enrutamiento avanzado:
astro.config.mjs
```
import { defineConfig } from 'astro/config';

export default defineConfig({
  // specify a different file for advanced routing configuration:
  fetchFile: './src/router.ts',
  // or disable advanced routing entirely:
  // fetchFile: null,
});
```
Renombrar tu archivo a algo diferente (ej. src/fetcher.ts, src/main.ts), y actualizar cualquier import que lo referencie.

Nuevo procesador de Markdown por defecto: Sätteri

PR de implementación: feat: make Sätteri the default Markdown pipeline (#16966)

Astro ahora renderiza tus archivos .md y .mdx con Sätteri, su pipeline nativo de Markdown, en lugar del pipeline de remark/rehype. Como resultado, @astrojs/markdown-remark ya no se instala por defecto.

¿Qué debo hacer?

Si no usas plugins de remark o rehype, no necesitas hacer nada. Tu Markdown y MDX ahora serán renderizados por Sätteri, que aplica GitHub-Flavored Markdown y SmartyPants igual que antes.

Si dependes de plugins de remark y rehype, puedes portarlos a plugins MDAST o HAST de Sätteri. Si dependes de plugins de recma, o si aún no estás listo o no puedes portar tus plugins de remark y rehype, puedes quedarte en el pipeline de unified().

Para seguir usando plugins de unified:

Instala @astrojs/markdown-remark:
- npm
- pnpm
- Yarn
Ventana de la terminal
npm install @astrojs/markdown-remark
Ventana de la terminal
pnpm add @astrojs/markdown-remark
Ventana de la terminal
yarn add @astrojs/markdown-remark

Configura unified() como tu procesador de Markdown:

import { defineConfig } from 'astro/config';
import { unified } from '@astrojs/markdown-remark';

export default defineConfig({
  markdown: {
    processor: unified(),
  },
});

Las opciones deprecadas markdown.remarkPlugins, markdown.rehypePlugins, y markdown.remarkRehype aún funcionan, pero ahora también requieren que @astrojs/markdown-remark esté instalado.

Nuevo manejo de espacios en blanco por defecto: `compressHTML: 'jsx'`

PR de implementación: feat: make jsx whitespace handling the default (#16965)

En Astro v6.x, el manejo de espacios en blanco usaba compresión consciente del HTML por defecto. Esto significa que Astro preservaba un único espacio entre elementos inline, siguiendo las reglas HTML.

En Astro v7.0, el valor por defecto de compressHTML ha cambiado de true a 'jsx'. Ahora, Astro elimina los espacios en blanco de tu HTML usando reglas JSX por defecto, de la misma manera que lo hacen frameworks como React.

El siguiente ejemplo se renderizaría como helloworld en Astro v7.0, en lugar de hello world en Astro v6.x:

<span>hello</span>
<em>world</em>

¿Qué debo hacer?

Inspecciona visualmente tu sitio web para asegurar que los espacios entre elementos se renderizan como se espera. Podrías no necesitar tomar ninguna acción adicional.

Si notas que faltan algunos espacios, identifica los componentes y páginas donde estás usando elementos inline. Luego, actualízalos para añadir un espacio explícito entre estos elementos usando {" "}:

<span>hello</span>
<em>world</em>
<span>hello</span> <em>world</em>

Si prefieres mantener el comportamiento anterior, establece compressHTML en true. También puedes usar compressHTML: false para preservar todos los espacios en blanco.

import { defineConfig } from 'astro/config';

export default defineConfig({
  compressHTML: true,
});

Deprecado

Las siguientes funcionalidades deprecadas ya no se soportan y ya no se documentan. Actualiza tu proyecto en consecuencia.

Algunas funcionalidades deprecadas pueden continuar funcionando temporalmente hasta que sean completamente removidas. Otras pueden silenciosamente no tener efecto, o lanzar un error pidiéndote que actualices tu código.

Deprecado: `getContainerRenderer()` desde las raíces de paquetes de integración

PR de implementación: fix(integrations): Export container renderers from a dedicated export path to fix bundling issues (#17093)

En Astro 6.x, el helper getContainerRenderer() usado con la Container API se importaba desde la raíz del paquete de una integración oficial (ej. @astrojs/react). Esto podía causar que los bundlers trajeran exports no relacionados y solo de build time desde la raíz del paquete cuando solo se necesitaba la Container API.

Astro 7.0 deprecá importar getContainerRenderer() desde la raíz del paquete de una integración en favor de un entrypoint dedicado container-renderer.

¿Qué debo hacer?

Actualiza tus imports de la Container API para usar el nuevo entrypoint container-renderer para cada integración oficial:

import { getContainerRenderer } from '@astrojs/react';
import { getContainerRenderer } from '@astrojs/react/container-renderer';

Este entrypoint está disponible para @astrojs/react, @astrojs/preact, @astrojs/solid-js, @astrojs/svelte, @astrojs/vue, y @astrojs/mdx.

Removido

Las siguientes funcionalidades han sido ahora enteramente removidas del código base y ya no se pueden usar. Algunas de estas funcionalidades pueden haber continuado funcionando en tu proyecto incluso después de su deprecación. Otras pueden haber silenciosamente no tenido efecto.

Los proyectos que ahora contienen estas funcionalidades removidas no podrán construirse, y ya no habrá documentación de soporte pidiéndote que elimines estas funcionalidades.

Removido: `@astrojs/db`

El paquete @astrojs/db ha sido removido en Astro v7.0 y ya no se mantiene.

¿Qué debo hacer?

Elimina @astrojs/db de las dependencias de tu proyecto y reemplázalo con una de las siguientes alternativas:

SQLite integrado de Node.js: Node.js ahora incluye un módulo node:sqlite integrado (disponible desde Node.js v22.5.0). Esta es una buena opción si estás usando el adapter de Node.js y estabas usando @astrojs/db para almacenamiento SQLite local.
Drizzle ORM: Si estabas usando @astrojs/db por su schema basado en Drizzle y API de consulta, puedes usar Drizzle directamente con cualquier base de datos soportada.
Otras librerías de base de datos: Usa cualquier librería de base de datos que se adapte a tu plataforma de despliegue (ej. Turso, PlanetScale, Neon).

Removido: internos expuestos de `astro:transitions`

PR de implementación: feat: remove deprecated astro:transitions internals (#16725)

En Astro 6.x, algunos helpers disponibles en astro:transitions y astro:transitions/client fueron deprecados.

En Astro 7.0, las siguientes APIs ya no pueden usarse en tu proyecto:

TRANSITION_BEFORE_PREPARATION
TRANSITION_AFTER_PREPARATION
TRANSITION_BEFORE_SWAP
TRANSITION_AFTER_SWAP
TRANSITION_PAGE_LOAD
isTransitionBeforePreparationEvent()
isTransitionBeforeSwapEvent()
createAnimationScope()

¿Qué debo hacer?

Elimina cualquier ocurrencia de createAnimationScope():

import { createAnimationScope } from 'astro:transitions';

Reemplaza cualquier ocurrencia de las otras APIs usando los nombres de eventos del lifecycle directamente:

import {
  TRANSITION_AFTER_SWAP,
  isTransitionBeforePreparationEvent,
} from 'astro:transitions/client';

console.log(isTransitionBeforePreparationEvent(event));
console.log(event.type === 'astro:before-preparation');

console.log(TRANSITION_AFTER_SWAP);
console.log('astro:after-swap');

Aprende más sobre todas las utilidades disponibles en la Referencia de la View Transitions Router API.

Contribuir Comunidad Patrocinar

Actualizar a Astro v7

Actualizar Astro

Cambios importantes

Actualizaciones de dependencias

Vite 8

¿Qué debo hacer?

Flags experimentales

Funcionalidades experimentales ahora estables:

Compilador de Rust

¿Qué debo hacer?

Diferencias en la salida de CSS

Nombre de archivo reservado: src/fetch.ts

¿Qué debo hacer?

Nuevo procesador de Markdown por defecto: Sätteri

¿Qué debo hacer?

Nuevo manejo de espacios en blanco por defecto: compressHTML: 'jsx'

¿Qué debo hacer?

Deprecado

Deprecado: getContainerRenderer() desde las raíces de paquetes de integración

¿Qué debo hacer?

Removido

Removido: @astrojs/db

¿Qué debo hacer?

Removido: internos expuestos de astro:transitions

¿Qué debo hacer?

Nombre de archivo reservado: `src/fetch.ts`

Nuevo manejo de espacios en blanco por defecto: `compressHTML: 'jsx'`

Deprecado: `getContainerRenderer()` desde las raíces de paquetes de integración

Removido: `@astrojs/db`

Removido: internos expuestos de `astro:transitions`