Actualizar a Astro v4

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

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

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

Actualizar Astro

Actualiza la versión de Astro y todas las integraciones oficiales de tu proyecto a las últimas versiones usando tu gestor de paquetes.

npm

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

pnpm

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

Yarn

# 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.

¿Necesitas continuar?

Después de actualizar Astro a la última versión, puede que no necesites hacer ningún cambio en tu proyecto.

Pero, si notas errores o comportamientos inesperados, consulta a continuación qué ha cambiado y podría necesitar actualización en tu proyecto.

Astro v4.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 v4.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 para las notas de release completas.

Flags experimentales de Astro v4.0 removidos

Elimina el flag experimental devOverlay y mueve cualquier configuración de i18n al nivel superior en astro.config.mjs:

astro.config.mjs

import { defineConfig } from 'astro/config';

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

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

Lee más sobre estas dos emocionantes funcionalidades y más en el post del blog de v4.0!

Actualizaciones

Cualquier actualización mayor de las dependencias de Astro puede causar cambios importantes en tu proyecto.

Actualizado: Vite 5.0

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

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

¿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 para sus cambios importantes y actualiza tu proyecto según sea necesario. No hay cambios importantes en Astro mismo.

Actualizado: dependencias unified, remark, y rehype

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

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

¿Qué debo hacer?

Si usabas paquetes remark/rehype personalizados, actualiza todos a la última versión usando tu gestor de paquetes para asegurar que soportan unified v11. Los paquetes que estás usando se pueden encontrar en astro.config.mjs.

No debería haber cambios importantes significativos si usas paquetes actualizados activamente, pero algunos paquetes podrían no ser todavía compatibles con unified v11. Inspecciona visualmente tus páginas Markdown/MDX antes de desplegar para asegurar que tu sitio funciona como se espera.

Cambios importantes

Los siguientes cambios se consideran cambios importantes en Astro. Los cambios importantes pueden o no proporcionar compatibilidad con versiones anteriores temporal, y toda la documentación se actualiza para referirse solo al código actual soportado.

Si necesitas consultar la documentación para un proyecto v3.x, puedes navegar este snapshot (sin mantenimiento) de la documentación de antes de que v4.0 fuera lanzado.

Renombrado: entrypoint (Integrations API)

En Astro v3.x, la propiedad de la API de integraciones injectRoute que especificaba el entry point 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 está deprecada pero continuará funcionando y registra una advertencia pidiéndote que actualices 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 librería que quiere soportar tanto Astro 3 como 4, puedes especificar tanto entryPoint como entrypoint, en cuyo caso no se registrará una advertencia.

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

Cambiado: signature de app.render en Integrations API

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

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

¿Qué debo hacer?

Si estás manteniendo un adapter, la signature actual continuará funcionando hasta la próxima versión mayor. Para migrar a la nueva signature, 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: los adapters ahora deben especificar las funcionalidades soportadas

En Astro v3.x, los adapters no estaban obligados a especificar las funcionalidades que soportan.

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

¿Qué debo hacer?

Los autores de adapters necesitan pasar la opción supportedAstroFeatures{} para especificar una lista de funcionalidades que soportan.

my-adapter.mjs

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'
          }
        });
      },
    },
  };
}

Removido: propiedad path de lenguaje Shiki

En Astro v3.x, un lenguaje Shiki pasado a markdown.shikiConfig.langs se convertía automáticamente a un lenguaje compatible con Shikiji. Shikiji es la herramienta interna usada por Astro para resaltado de sintaxis.

Astro v4.0 elimina el soporte para la propiedad path de un lenguaje Shiki, que era confusa de configurar. Se reemplaza por un import que puede pasarse a langs directamente.

¿Qué debo hacer?

El archivo JSON del lenguaje debería importarse y pasarse a la opción en su lugar.

astro.config.js

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

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

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: handleForms para eventos submit de View Transitions

En Astro v3.x, los proyectos que usaban el componente <ViewTransitions /> debían optar por manejar eventos submit para elementos form. Esto se hacía pasando una prop handleForms.

Astro v4.0 maneja eventos submit para elementos form por defecto cuando se usa <ViewTransitions />. La prop handleForms ha sido deprecada y ya no tiene ningún efecto.

¿Qué debo hacer?

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

src/pages/index.astro

---
import { ViewTransitions } from "astro:transitions";
---
<html>
  <head>
    <ViewTransitions handleForms />
  </head>
  <body>
    <!-- stuff here -->
  </body>
</html>

Para excluirte del manejo de eventos submit, añade el atributo data-astro-reload a los elementos form relevantes.

src/components/Form.astro

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

Funcionalidades previamente deprecadas ahora removidas

Las siguientes funcionalidades deprecadas 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: retornar objetos simples desde endpoints

En Astro v3.x, retornar objetos simples desde endpoints estaba deprecado, pero todavía se soportaba para mantener compatibilidad con Astro v2. Una utilidad ResponseWithEncoding también se proporcionaba para facilitar la migración.

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

¿Qué debo hacer?

Actualiza tus endpoints para retornar un objeto Response directamente.

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

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

Removido: build.split y build.excludeMiddleware

En Astro v3.0, las opciones de configuración de build build.split y build.excludeMiddleware estaban deprecadas y reemplazadas con opciones de configuración del adapter para realizar las mismas tareas.

Astro v4.0 elimina estas propiedades por completo.

¿Qué debo hacer?

Si estás usando el build.split o build.excludeMiddleware deprecado, debes ahora eliminarlos ya que ya no existen.

Consulta la guía de migración de v3 para actualizar estas propiedades de middleware deprecadas con configuraciones del adapter.

Removido: Astro.request.params

En Astro v3.0, la API Astro.request.params estaba deprecada, pero se preservó por compatibilidad con versiones anteriores.

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

¿Qué debo hacer?

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

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

Removido: markdown.drafts

En Astro v3.0, usar markdown.drafts para controlar la construcción de posts borrador estaba deprecado.

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

¿Qué debo hacer?

Si estás usando el markdown.drafts deprecado, debes ahora eliminarlo ya que ya no existe.

Para continuar marcando algunas páginas en tu proyecto como borradores, migra a content collections y filtra manualmente las páginas con la propiedad de frontmatter draft: true en su lugar.

Removido: getHeaders()

En Astro v3.0, el export de Markdown getHeaders() estaba deprecado y reemplazado por getHeadings().

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

¿Qué debo hacer?

Si estás usando el getHeaders() deprecado, debes ahora eliminarlo ya que ya no existe. Reemplaza cualquier instancia con getHeadings(), que es el reemplazo soportado.

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

Removido: usar rss en getStaticPaths()

En Astro v3.0, usar el helper rss deprecado en getStaticPaths() lanzaría un error.

Astro v4.0 elimina este helper por completo.

¿Qué debo hacer?

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

Removido: nombres de métodos HTTP en minúsculas

En Astro v3.0, usar nombres de métodos de petición HTTP en minúsculas (get, post, put, all, del) estaba deprecado.

Astro v4.0 elimina el soporte para nombres en minúsculas por completo. Todos los métodos de petición HTTP deben ahora escribirse usando mayúsculas.

¿Qué debo hacer?

Si estás usando los nombres en minúsculas deprecados, debes ahora reemplazarlos con sus equivalententes en mayúsculas.

Consulta la guía de migración de v3 para guía sobre el uso de métodos de petición HTTP en mayúsculas.

Removido: redirecciones 301 cuando falta un prefijo base

En Astro v3.x, el preview server de Astro retornaba una redirección 301 al acceder a 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 preview server está en ejecución, coincidiendo con el comportamiento del dev server.

¿Qué debo hacer?

Al usar el preview server de Astro, todas tus importaciones de assets estáticos y URLs del directorio public deben tener el valor de base como prefijo en la ruta.

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

src/pages/index.astro

// To access public/images/my-image.png:

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

Removido: auto-conversión de astro/client-image

En Astro v3.x, el tipo astro/client-image (usado para la integración de imágenes deprecada) fue removido pero se auto-convertía al tipo por defecto de Astro astro/client si se encontraba en tu archivo env.d.ts.

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

¿Qué debo hacer?

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

src/env.d.ts

  /// <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 añade un enlace abajo!

Problemas conocidos

Por favor consulta los issues de Astro en GitHub para cualquier problema reportado, o para reportar un issue tú mismo.