Actualizar Astro

Esta guía cubre cómo actualizar tu versión de Astro y dependencias relacionadas, cómo aprender qué ha cambiado de una versión a la siguiente, y cómo entender el sistema de versionado de Astro y las correspondientes actualizaciones de documentación.

¿Qué ha cambiado?

La última versión de Astro es v7.0.3.

Puedes encontrar una lista exhaustiva de todos los cambios en el changelog de Astro, e instrucciones importantes para actualizar a cada nueva versión mayor en nuestras guías de actualización.

Actualiza a la última versión

Actualiza la versión de Astro de tu proyecto y todas las integraciones oficiales a las últimas versiones con un solo comando 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

Actualización manual

Para actualizar Astro y las integraciones a sus versiones actuales manualmente, usa el comando apropiado para tu gestor de paquetes.

# Example: upgrade Astro with React and Partytown integrations
npm install astro@latest @astrojs/react@latest @astrojs/partytown@latest

# Example: upgrade Astro with React and Partytown integrations
pnpm add astro@latest @astrojs/react@latest @astrojs/partytown@latest

# Example: upgrade Astro with React and Partytown integrations
yarn add astro@latest @astrojs/react@latest @astrojs/partytown@latest

Instala un número de versión específico

Para instalar una versión específica de Astro o integraciones, usa el comando apropiado para tu gestor de paquetes.

npm install astro@4.5.3 @astrojs/react@3.0.10

pnpm add astro@4.5.3 @astrojs/react@3.0.10

yarn add astro@4.5.3 @astrojs/react@3.0.10

Actualizaciones de documentación

Esta documentación se actualiza para cada versión menor y versión mayor. Cuando se añaden nuevas características, o cambia el uso existente, la documentación se actualizará para reflejar el comportamiento actual de Astro. Si tu proyecto no está actualizado, puedes notar que algunos comportamientos no coinciden con la documentación actualizada.

Las nuevas características se añaden a la documentación con el número de versión específico en el que fueron añadidas. Esto significa que si no has actualizado a la última versión de Astro, algunas características documentadas pueden no estar disponibles. ¡Siempre verifica el número de versión Añadido en: y asegúrate de que tu proyecto esté actualizado antes de intentar usar nuevas características!

Si no has actualizado a la última versión mayor de Astro, puedes encontrar diferencias significativas entre la documentación de Astro y el comportamiento de tu proyecto. Recomendamos encarecidamente actualizar a la versión mayor actual de Astro tan pronto como puedas. Tanto el código como la documentación para versiones anteriores no tienen soporte.

Guías de Actualización

Después de cada versión mayor, encontrarás una guía de actualización con información sobre cambios importantes e instrucciones para actualizar el código de tu proyecto.

Las páginas principales de documentación de Astro siempre son precisas para la última versión publicada de Astro. No describen ni comparan cómo funcionaban las cosas en versiones anteriores, ni destacan comportamiento actualizado o cambiado.

Consulta las guías de actualización a continuación para una explicación de los cambios, comparando la nueva versión con la anterior. Las guías de actualización incluyen todo lo que podría requerir que cambies tu propio código: cambios disruptivos, deprecaciones, eliminaciones y reemplazos de características, así como guía de uso actualizada. Cada cambio a Astro incluye una sección "¿Qué debería hacer?" para ayudarte a actualizar exitosamente el código de tu proyecto.

Documentación anterior (sin mantenimiento)

La documentación para versiones anteriores de Astro no se mantiene, pero está disponible como una instantánea estática. Usa estas versiones de documentación si no puedes actualizar tu proyecto, pero aún deseas consultar guías y referencia:

Versionado semántico

Astro intenta adherirse tanto como sea posible al versionado semántico, que es un conjunto de reglas que los desarrolladores usan para determinar cómo asignar un número de versión a una publicación. El versionado semántico sigue un patrón predecible para informar a los usuarios del tipo de cambios que pueden esperar de una versión a la siguiente.

El versionado semántico aplica un patrón de X.Y.Z para los números de versión de software. Estos valores representan actualizaciones mayor (X), menor (Y), y patch (Z).

Cambios de patch

Los cambios de patch son los cambios menos disruptivos. No cambian la forma en que usas Astro, y no se requiere ningún cambio en tu propio código cuando actualizas.

Cuando Astro publica una versión "patch", el último número aumenta. (ej. astro@4.3.14 -> astro@4.3.15)

Los patches pueden ser publicados por razones como:

Internal changes that do not change Astro’s functionality:
- refactorizaciones
- mejoras de rendimiento
- aumento o cambio en la cobertura de tests
- alineación con la documentación establecida y el comportamiento esperado
Mejoras al logging y mensajes de error.
Re-publicaciones después de una publicación fallida.

Los cambios de patch también incluyen la mayoría de las correcciones de errores, incluso en casos donde los usuarios estaban aprovechando un comportamiento existente no intencionado o indeseable.

Cambios menores

Las versiones menores principalmente introducen nuevas características y mejoras que puedes desear probar, pero no requieren cambios en tu código. Algunas características existentes también pueden ser deprecadas (marcadas para eliminación en una versión futura mientras siguen funcionando) en una versión menor, dándote la oportunidad de prepararte para su eventual eliminación.

Las versiones menores incluyen cambios como:

Deprecaciones de características/opciones existentes con una advertencia de que serán eliminadas en una próxima versión mayor.
Introducción de nuevas funcionalidades.
Introducción de nuevas opciones en los hooks de integración.
Introducción de nuevas funcionalidades en astro/app, notablemente usado para crear nuevos adaptadores.

Una versión menor también puede incluir cambios más pequeños de patch al mismo tiempo.

Cambios mayores

Las versiones mayores incluirán cambios disruptivos en al menos parte del código existente. Estos cambios disruptivos siempre están documentados en una guía "Actualiza a vX" en Astro.

Las versiones mayores permiten a Astro hacer cambios significativos no solo en la lógica interna, sino también en el comportamiento y uso previsto. La documentación se actualizará para reflejar solo la última versión, y instantáneas estáticas sin mantener de documentación anterior están disponibles como un registro histórico para proyectos antiguos que aún no se han actualizado.

Las versiones mayores incluyen cambios como:

Eliminación de funcionalidades previamente deprecadas.
Cambios de funcionalidades existentes.
Cambios de opciones existentes en los hooks de integración.
Cambios de opciones y funcionalidades existentes en astro/app, notablemente usado para crear nuevos adaptadores.

Una versión mayor también puede incluir algunos cambios no disruptivos y mejoras que normalmente se publicarían por separado en una versión menor o de patch.

Excepciones

Características experimentales. Publicar versiones de Astro sin adherirse al versionado semántico da a los desarrolladores de Astro la mayor flexibilidad para explorar, e incluso cambiar radicalmente de rumbo, durante el desarrollo de características experimentales. Por lo tanto, el comportamiento de estas características puede romperse en cambios menores y de patch.

Estas características suelen estar acompañadas por un Request for Consideration (RFC) stage 3 público y en curso. Se espera que los usuarios beta sigan las actualizaciones, y dejen feedback temprano en la discusión para ayudar a guiar el desarrollo de estas características.

Una vez que estas características salgan de su período experimental, seguirán el contrato normal de versionado semántico.
Mejoras a la documentación (ej. referencia y mensajes de error). Se construyen desde el código fuente para el repositorio docs. Esto permite a Astro actualizar rápidamente correcciones y mejoras de documentación en los casos donde el contenido fuente de la documentación está almacenado en el repositorio principal astro.

Soporte y políticas de actualización de Node.js

Soporte

Astro soporta la versión última Maintenance LTS de Node.js.
Astro soporta la versión actual Active LTS de Node.js
Astro puede soportar versiones impares de Node.js.

Actualización

Las siguientes reglas definen cuándo Astro puede deprecar, eliminar, o añadir soporte para versiones de Node.js:

Las versiones impares de Node.js pueden ser deprecadas y/o eliminadas cuando se publique la siguiente versión par de Node.js. Este cambio puede ocurrir en una versión menor de Astro, después de un período razonable de soporte extendido según lo decida el equipo Core de Astro.
Upgrading the minimum Maintenance LTS (within the same major range, e.g. from 22.14.* to 22.20.*) version of Node.js can occur in a minor release of Astro.
- Excepción de seguridad: Si se divulga y corrige una falla de seguridad en Node.js que afecta a Astro, el equipo Core puede incrementar la versión mínima de la Maintenance LTS en una versión de patch.
Upgrading minor or major versions of Node.js (not Maintenance LTS) occurs only in major versions of Astro.
- Excepción de seguridad: Si se divulga y corrige una falla de seguridad en Node.js que afecta a Astro, el equipo Core puede incrementar la versión mínima en una versión menor.

Mantenimiento extendido

El equipo Core proporcionará mantenimiento extendido solo para correcciones de seguridad para una versión mayor anterior. Esto significa que si la versión mayor actual es v4.*, el equipo Core retroportará las correcciones de seguridad y publicará una nueva versión v3.*.

Contribuir Comunidad Patrocinar