Actualizar a Astro v4

Esta guía te ayudará a migrar de Astro v3 a Astro v4.

¿Necesitas actualizar un proyecto más antiguo a la v3? Consulta nuestra guía de migración anterior.

¿Necesitar ver la documentation de la v3? Visita este sitio de documentación anterior (spanshot no mantenida de la v3.6).

Actualizar Astro

Actualiza la versión de Astro y todas las integraciones oficiales en tu proyecto a la última versión utilizando tu administrador de paquetes.

# Actualiza Astro y las integraciones oficiales al mismo tiempo
npx @astrojs/upgrade

# Actualiza Astro y las integraciones oficiales al mismo tiempo
pnpm dlx @astrojs/upgrade

# Actualiza Astro y las integraciones oficiales al mismo tiempo
yarn dlx @astrojs/upgrade

También puedes actualizar tus integraciones de Astro manualmente si es necesario, y puede que también necesites actualizar otras dependencias en tu proyecto.

Astro v4.0 incluye cambios potencialmente importantes, así como la eliminación de algunas funciones obsoletas.

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

Consulta el registro de cambios para ver todas las notas de la versión.

Astro v4.0 Banderas Experimentales Eliminadas

Elimina la bandera experimental devOverlay y mueve cualquier configuración i18n al nivel superior en astro.config.mjs:

import { defineConfig } from 'astro/config';

export default defineConfig({
  experimental: {
    devOverlay: true,
    i18n: {
      defaultLocale: "en",
      locales: ["en", "fr", "pt-br", "es"],
    }
  },
  i18n: {
    defaultLocale: "en",
    locales: ["en", "fr", "pt-br", "es"],
  },
})

Estas configuraciones, i18n y la renombrada devToolbar, están ahora disponibles en Astro v4.0.

¡Lee más acerca de estas dos emocionantes características y más en la entrada del blog de la v4.0!

Actualizaciones

Cualquier actualización principal a las dependencias de Astro podría ocasionar cambios que afecten a la compatibilidad en tu proyecto.

Actualizado: Vite 5.0

En Astro v3.0, Vite 4 se utilizó como servidor de desarrollo y empaquetador de producción.

Astro v4.0 actualiza de Vite 4 a Vite 5.

¿Qué debo hacer?

Si estás usando plugins específicos de Vite, configuraciones, o APIs, consulta la guía de migración de Vite para ver los cambios importantes y actualiza tu proyecto según sea necesario. No hay cambios importantes en Astro en sí mismo.

Actualizado: dependencias unified, remark y rehype

En Astro v3.x, unified v10 y sus paquetes relacionados compatibles remark/rehype se utilizaban para procesar Markdown y MDX.

Astro v4.0 actualiza unified a la v11 y los demás paquetes remark/rehype a la última versión.

¿Qué debo hacer?

Si utilizabas paquetes personalizados de remark/rehype, actualízalos todos a la última versión utilizando tu administrador de paquetes para asegurarte de que sean compatibles con unified v11. Puedes encontrar los paquetes que estás utilizando en astro.config.mjs.

No debería haber cambios importantes significativos si utilizas paquetes que se actualizan activamente, pero algunos paquetes pueden no ser compatibles aún con unified v11. Inspecciona visualmente tus páginas Markdown/MDX antes de desplegar para asegurarte que tu sitio funciones según lo previsto.

Cambios importantes

Los siguientes cambios son considerados importantes en Astro. Cambios importantes pueden o no porporcionar compatibilidad temporal con versiones anteriores, y toda la documentación es actualizada para referirse solo al código actual y compatible.

Si necesitas referirte a la documentacion para un proyecto v3.x, puedes consultar esta (sin mantenimiento) spanshot de los documentos anteriores a la publicación de la v4.0.

Renombrado: `entrypoint` (API de integraciones)

En Astro v3.x, la propiedad de la API de integraciones injectRoute que especificaba el punto de entrada de la ruta se llamaba entryPoint.

Astro v4.0 renombra esta propiedad a entrypoint para ser consistente con otras APIs de Astro. La propiedad entrypoint es obsoleta pero continuará funcionando y mostrará un aviso pidiendote que actualizes tu código.

¿Qué debo hacer?

Si tienes integraciones que usan la API injectRoute, renombra la propiedad entryPoint a entrypoint. Si eres un autor de librerias que quiere soportar tanto Astro 3 como 4, puedes especificar tanto entryPoint como entrypoint, en cuyo caso no se registrará un aviso.

injectRoute({
  pattern: '/fancy-dashboard',
  entryPoint: '@fancy/dashboard/dashboard.astro'
  entrypoint: '@fancy/dashboard/dashboard.astro'
});

Cambiado: Firma `app.render` en la API de integraciones

En Astro v3.0, el método app.render() aceptaba routeData y locals como argumentos separados y opcionales.

Astro v4.0 cambia la firma de app.render(). Estas dos propiedades están ahora disponibles en un único objeto. Tanto el objeto como estas dos propiedades siguen siendo opcionales.

¿Qué debo hacer?

Si estás manteniendo un adaptador, la firma actual seguirá funcionando hasta la siguiente versión principal. Para migrar a esta nueva firma, pasa routeData y locals como propiedades de un objeto en lugar de como múltiples argumentos independientes.

app.render(request, routeData, locals)
app.render(request, { routeData, locals })

Cambiado: Ahora los adaptadores deben especificar las caracteristicas compatibles

En Astro v3.x, los adaptadores no debían especificar las caracteristicas que admitían.

Astro v4.0 requiere que los adaptadores pasen la propiedad supportedAstroFeatures{} para especificar una lista de las caracteristicas que soportan. Esta propiedad ya no es opcional.

¿Qué debo hacer?

Los autores de adaptadores necesitan pasar la opción supportedAstroFeatures{} para especificar una lista de caracteristicas que admiten.

export default function createIntegration() {
  return {
    name: '@matthewp/my-adapter',
    hooks: {
      'astro:config:done': ({ setAdapter }) => {
        setAdapter({
          name: '@matthewp/my-adapter',
          serverEntrypoint: '@matthewp/my-adapter/server.js',
          supportedAstroFeatures: {
              staticOutput: 'stable'
          }
        });
      },
    },
  };
}

Eliminado: Propiedad `path` del lenguaje Shiki

En Astro v3.x, un lenguajes de Shiki que era pasado a markdown.shikiConfig.langs era automáticamente convertido a un lenguaje compatible con Shikiji. Shikiji es la herramienta interna utilizada por Astro para resaltar la sintaxis.

Astro v4.0 elimina el soporte a la porpiedad path de un lenguaje Shiki, que era confusa de configurar. Se sustituye por una importación que se puede pasar a langs directamente.

¿Qué debo hacer?

El archivo de lenguaje JSON debe importarse y pasarse a la opción en su lugar.

 import customLang from './custom.tmLanguage.json'

export default defineConfig({
  markdown: {
    shikiConfig: {
      langs: [
       { path: '../../custom.tmLanguage.json' },
       customLang,
      ],
    },
  },
})

Obsoleto

Las siguientes caracteristicas obsoletas ya no son compatibles y no está documentadas. Por favor actualiza tu proyecto en consecuencia.

Algunas caracteristicas obsoletas pueden continuar funcionando temporalmente hasta que sean completamente eliminadas. Otras pueden no tener ningún efecto, o arrojar un error que te pida que actualizes tu código.

Obsoleto: `handleForms` para eventos `submit` de View Transitions

En Astro v3.x, los proyectos que utilizaban el componente <ViewTransitions /> debían activar la gestión de eventos submit para los elementos form. Esto se lograba mediante la inclusión de la propiedad handleForms.

Astro v4.0 gestiona los eventos submit para elementos form por defecto cuando se utiliza <ViewTransitions />. La propiedad handleForms ha quedado obsoleta y ya no tiene ningún efecto.

¿Qué debo hacer?

Elimina la propiedad handleForms de tu componente ViewTransitions. Ya no es necesaria.

---
import { ViewTransitions } from "astro:transitions";
---
<html>
  <head>
    <ViewTransitions handleForms />
  </head>
  <body>
    <!-- cosas aquí -->
  </body>
</html>

Para optar por no gestionar el evento submit, agrega el atributo data-astro-reload a los elementos form correspondientes.

<form action="/contact" data-astro-reload>
  <!-- -->
</form>

Características previamente obsoletas ahora eliminadas

Las siguientes características obsoletas han sido completamente eliminadas del código base y ya no se pueden utilizar. Algunas de estas características pueden haber seguido funcionando en tu proyecto incluso después de su eliminación. Otras pueden haber tenido silenciosamente ningún efecto.

Los proyectos que ahora contengan estas funciones eliminadas no se podrán compilar, y ya no habrá ninguna documentación de apoyo que te indique que elimines estas funciones.

Eliminado: Retornar objetos simples desde endpoints

En Astro v3.x, retornar objetos simples desde endpoints se marcó como obsoleto, pero se conservó su soporte para mantener la compatibilidad con Astro v2. También se proporcionó una utilidad ResponseWithEncoding para facilitar la migración.

Astro v4.0 elimina el soporte para objetos simples y requiere que los endpoints retornen siempre un Response. La utilidad ResponseWithEncoding también fué eliminada en favor de un tipo Response adecuado.

¿Qué debo hacer?

Actualiza tus endpoints para retornar un objeto Response directamente.

export async function GET() {
  return { body: { "title": "Blog de Bob" }};
  return new Response(JSON.stringify({ "title": "Blog de Bob" }));
}

Para eliminar el uso de ResponseWithEncoding, refactoriza tu código para usar un ArrayBuffer en su lugar:

export async function GET() {
  const file = await fs.readFile('./bob.png');
  return new ResponseWithEncoding(file.toString('binary'), undefined, 'binary');
  return new Response(file.buffer);
}

Eliminado: `build.split` y `build.excludeMiddleware`

En Astro v3.0, las opciones de configuración de construcción build.split y build.excludeMiddleware fueron marcadas como obsoletas y reemplazadas con opciones de configuración de adaptadores para realizar las mismas tareas.

Astro v4.0 elimina por completo estas propiedades.

¿Qué debo hacer?

Si estás utilizando las funciones obsoletas build.split or build.excludeMiddleware, debes eliminarlas ahora debido a que ya no existen.

Por favor consulta la guía de migración de la v3 para actualizar estas propiedades de middleware obsoletas con la configuración de adaptadores.

Eliminado: `Astro.request.params`

En Astro v3.0, la API Astro.request.params quedó obsoleta, pero se conservó por compatibilidad con versiones anteriores.

Astro v4.0 elimina por completo esta opción.

¿Qué debo hacer?

Actualiza todas las ocurrencias a Astro.params, que es el reemplazo admitido.

const { id } = Astro.request.params;
const { id } = Astro.params;

Eliminado: `markdown.drafts`

En Astro v3.0, el uso de markdown.drafts para controlar la construcción de borradores de publicaciones quedó obsoleto.

Astro v4.0 elimina por completo esta opción.

¿Qué debo hacer?

Si estás utilizando la función obsoleta markdown.drafts, debes eliminarla ahora debido a que ya no existe.

Para seguir marcando algunas página en tu proyecto como borradores, migra a colecciones de contenido y filtra manualmente las páginas con la propiedad draft: true en el frontmatter en su lugar.

Eliminado: `getHeaders()`

En Astro v3.0 la exportación Markdown getHeaders() quedó obsoleta y se reemplazó por getHeadings().

Astro v4.0 elimina por completo esta opción.

¿Qué debo hacer?

Si estás usando la función obsoleta getHeaders(), debes eliminarla ahora debido a que esta ya no existe. Reemplaza cualquier instancia con getHeadings(), que es el reemplazo admitido.

const posts = await Astro.glob('../content/blog/*.mdx');
const firstPostHeadings = posts.at(0).getHeaders();
const firstPostHeadings = posts.at(0).getHeadings();

Eliminado: Usando `rss` en `getStaticPaths()`

En Astro v3.0, utilizar el helper obsoleto rss en getStaticPaths() generaría un error.

Astro v4.0 elimina por completo este helper.

¿Qué debo hacer?

Si estás usando el método no soportado para generar feeds RSS, ahora debes usar la integración @astrojs/rss para una configuración RSS completa.

Eliminado: Nombres de métodos HTTP en minúsculas

En Astro v3.0, el uso de minúsculas en los nombres de métodos de solicitud HTTP (get, post, put, all, del) quedó obsoleto.

Astro v4.0 elimina completamente el soporte para los nombres en minúsculas. Todos los metodos de solicitud HTTP deben de escribirse ahora en mayúsculas.

¿Qué debo hacer?

Si estás utilizando los nombres obsoletos en minúsculas, ahora debes sustituirlos por sus equivalentes en mayúsculas.

Por favor consulta la guía de migración de la v3 para obtener orientación sobre el uso de métodos de solicitud HTTP en mayúsculas.

Eliminado: Redirecciones 301 cuando falta un prefijo `base`

En Astro v3.x, el servidor de vista previa de Astro devolvía una redirección 301 al acceder a los assets del directorio public sin una ruta base.

Astro v4.0 retorna un estado 404 sin un prefijo de ruta base para los assets del directorio public cuando el servidor de vista previa se está ejecutando, coincidiendo con el comportamiento del servidor de desarrollo.

¿Qué debo hacer?

Cuando utilizes el servidor de vista previa, todas tus importaciones de assets estáticos y URLs desde el directorio public deben de tener el valor base como prefijo en la ruta.

El siguiente ejemplo muestra el atributo src necesario para mostrar una imagen desde la carpeta public cuando base: '/docs' está configurado:

// Para acceder a public/images/my-image.png:

<img src="/docs/images/my-image.png" alt="">

Eliminado: Auto-conversión de `astro/client-image`

En Astro v3.x, se eliminó el tipo astro/client-image (utilizado para la integración de imágenes obsoleta), pero se convirtió automáticamente al tipo predeterminado de Astro astro/client si se encontraba en tu archivo env.d.ts.

Astro v4.0 ignora astro/client-image y no actualizará automáticamente env.d.ts por ti.

¿Qué debo hacer?

Si tenías configurados tipos para @astrojs/image en src/env.d.ts y la actualización a la v3.0 no convirtió automáticamente los tipos por ti, reemplaza manualmente el tipo astro/client-image con astro/client.

  /// <reference types="astro/client-image" />
  /// <reference types="astro/client" />

Recursos de la comunidad

¿Conoces un buen recurso para Astro v4.0? ¡Edita esta página y agrega un enlace a continuación!

Errores conocidos

Por favor consulta los issues de Astro en GitHub para cualquier errore reportado o para presentar un error tú mismo.

Actualizar a Astro v4

Actualizar Astro

Astro v4.0 Banderas Experimentales Eliminadas

Actualizaciones

Actualizado: Vite 5.0

¿Qué debo hacer?

Actualizado: dependencias unified, remark y rehype

¿Qué debo hacer?

Cambios importantes

Renombrado: entrypoint (API de integraciones)

¿Qué debo hacer?

Cambiado: Firma app.render en la API de integraciones

¿Qué debo hacer?

Cambiado: Ahora los adaptadores deben especificar las caracteristicas compatibles

¿Qué debo hacer?

Eliminado: Propiedad path del lenguaje Shiki

¿Qué debo hacer?

Obsoleto

Obsoleto: handleForms para eventos submit de View Transitions

¿Qué debo hacer?

Características previamente obsoletas ahora eliminadas

Eliminado: Retornar objetos simples desde endpoints

¿Qué debo hacer?

Eliminado: build.split y build.excludeMiddleware

¿Qué debo hacer?

Eliminado: Astro.request.params

¿Qué debo hacer?

Eliminado: markdown.drafts

¿Qué debo hacer?

Eliminado: getHeaders()

¿Qué debo hacer?

Eliminado: Usando rss en getStaticPaths()

¿Qué debo hacer?

Eliminado: Nombres de métodos HTTP en minúsculas

¿Qué debo hacer?

Eliminado: Redirecciones 301 cuando falta un prefijo base

¿Qué debo hacer?

Eliminado: Auto-conversión de astro/client-image

¿Qué debo hacer?

Recursos de la comunidad

Errores conocidos

Renombrado: `entrypoint` (API de integraciones)

Cambiado: Firma `app.render` en la API de integraciones

Eliminado: Propiedad `path` del lenguaje Shiki

Obsoleto: `handleForms` para eventos `submit` de View Transitions

Eliminado: `build.split` y `build.excludeMiddleware`

Eliminado: `Astro.request.params`

Eliminado: `markdown.drafts`

Eliminado: `getHeaders()`

Eliminado: Usando `rss` en `getStaticPaths()`

Eliminado: Redirecciones 301 cuando falta un prefijo `base`

Eliminado: Auto-conversión de `astro/client-image`