Actualizar a Astro v3

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

¿Necesitas actualizar un proyecto más antiguo a la versión v2? Consulta nuestra guía de migración anterior para obtener más información.

Actualizar Astro

Actualiza la versión de Astro en tu proyecto a la última versión utilizando tu administrador de paquetes. Si estás utilizando integraciones de Astro, por favor también actualiza esas integraciones a la última versión.

npm

# Actualizar a Astro v3.x
npm install astro@latest

# Ejemplo: actualizar las integraciones de React y Tailwind
npm install @astrojs/react@latest @astrojs/tailwind@latest

pnpm

# Actualizar a Astro v3.x
pnpm add astro@latest

# Ejemplo: actualizar las integraciones de React y Tailwind
pnpm add @astrojs/react@latest @astrojs/tailwind@latest

Yarn

# Actualizar a Astro v3.x
yarn add astro@latest

# Ejemplo: actualizar las integraciones de React y Tailwind
yarn add @astrojs/react@latest @astrojs/tailwind@latest

¿Necesitas continuar?

¡Después de actualizar Astro a la última versión, es posible que no necesites realizar ningún cambio en tu proyecto en absoluto!

Sin embargo, si notas errores o comportamientos inesperados, por favor revisa a continuación los cambios que se han realizado y que podrían requerir actualizaciones en tu proyecto.

Astro v3.0: Banderas Experimentales Eliminadas

Elimina las siguientes banderas experimentales de astro.config.mjs:

astro.config.mjs

import { defineConfig } from 'astro/config';

export default defineConfig({
  experimental: {
    assets: true,
    viewTransitions: true,
  },
})

Estas características ahora están disponibles por defecto:

• View Transitions para transiciones de página animadas e islas persistentes. Consulta cambios importantes en la API de View Transitions y consejos de actualización si estabas utilizando esta bandera experimental.
• Una nueva API de servicios de imagen astro:assets para usar imágenes en Astro, incluyendo un nuevo componente <Image /> y la función getImage(). Por favor, lee los detallados consejos de actualización de imágenes sin importar si estabas usando esta bandera experimental para ver cómo esto podría afectar tu proyecto.

¡Lee más sobre estas dos emocionantes características y más en la publicación del blog sobre la versión 3.0!

Cambios importantes en Astro v3.0

Astro v3.0 incluye algunos cambios importantes, así como la eliminación de algunas características previamente deprecadas. Si tu proyecto no funciona como se esperaba después de actualizar a v3.0, consulta esta guía para obtener una visión general de todos los cambios importantes e instrucciones sobre cómo actualizar tu código base.

Mira el historial de cambios para ver las notas completas de la versión.

Eliminado: Soporte para Node 16

Node 16 tiene programado alcanzar su Fin de Vida en septiembre de 2023.

Astro v3.0 elimina por completo el soporte para Node 16 para que todos los usuarios de Astro puedan aprovechar las características más modernas de Node.

¿Qué debo hacer?

Asegúrate de que tanto tu entorno de desarrollo como tu entorno de implementación estén utilizando Node 18.14.1 o una versión superior.

1. Verifica tu versión local de Node utilizando:

   node -v

2. Revisa la documentación de tu entorno de despliegue para verificar que admita Node 18.

   Puedes especificar Node 18.14.1 para tu proyecto de Astro ya sea en una configuración en el panel de control o en un archivo .nvmrc.

   .nvmrc

   18.14.1

Eliminado: Soporte para TypeScript 4

En Astro v2.x, los ajustes preestablecidos de tsconfig.json incluyen soporte tanto para TypeScript 4.x como para 5.x.

Astro v3.0 actualiza los ajustes preestablecidos de tsconfig.json para solo admitir TypeScript 5.x. Ahora Astro asume que estás utilizando TypeScript 5.0 (marzo de 2023) o que tu editor lo incluye (p. ej. VS Code 1.77).

¿Qué debo hacer?

Si has instalado TypeScript localmente, actualiza al menos a la versión v5.0.

npm install typescript@latest --save-dev

Eliminado: @astrojs/image

En Astro v2.x, Astro ofrecía una integración oficial de imágenes que incluía los componentes <Image /> y <Picture />.

Astro v3.0 elimina por completo esta integración del código base. La nueva solución de Astro para imágenes es una API de servicios de imágenes integrada: astro:assets.

¿Qué debo hacer?

Elimina la integración @astrojs/image de tu proyecto. Deberás no solo desinstalar la integración, sino también actualizar o eliminar cualquier declaración de importación y los componentes existentes <Image /> y <Picture />. Es posible que también necesites configurar un servicio de procesamiento de imágenes preferido por defecto.

Encontrarás instrucciones completas y paso a paso para eliminar la antigua integración de imágenes en nuestra guía de Imágenes.

Migrar a astro:assets también traerá algunas nuevas opciones y características de imágenes que es posible que desees utilizar. ¡Por favor, consulta el Consejo de Actualización de Imágenes v3.0 completo para obtener todos los detalles!

astro.config.mjs

import { defineConfig } from 'astro/config';
import image from '@astrojs/image';

export default defineConfig({
  integrations: [
    image(),
  ]
})

Eliminado: Componente <Markdown />

En Astro v1.x, Astro marcó como obsoleto el componente <Markdown /> y lo movió a un paquete externo.

Astro v3.0 elimina por completo el paquete @astrojs/markdown-component. El componente <Markdown /> de Astro ya no funcionará en tu proyecto.

¿Qué debo hacer?

Elimina todas las instancias de @astrojs/markdown-component.

src/components/MyAstroComponent.astro

---
import Markdown from '@astrojs/markdown-component';
---

Para seguir utilizando un componente similar a <Markdown /> en tu código, considera usar integraciones de la comunidad como astro-remote. Asegúrate de actualizar las importaciones y atributos de tu componente <Markdown /> según sea necesario, de acuerdo con la documentación propia de la integración.

De lo contrario, elimina todas las referencias a la importación del componente <Markdown /> de Astro y el propio componente en tus archivos .astro. Tendrás que reescribir tu contenido directamente como HTML o importar Markdown desde un archivo .md.

Eliminado: APIs obsoletas de la versión 1.x

En Astro v1.x, Astro marcó como obsoletas las opciones de configuración, así como los tipos de atributos global y hoist para script/estilos. Estos se mantuvieron para compatibilidad con versiones anteriores.

Astro v3.0 elimina por completo estas API obsoletas. Ya no se pueden utilizar en tu proyecto de Astro.

¿Qué debo hacer?

Si continúas utilizando las APIs de la versión v1.x, utiliza en su lugar las nuevas API para cada funcionalidad:

• Opciones de configuración obsoletas: Consulta la guía de migración 0.26 (EN)
• Tipos de atributos script/estilo obsoletos: Consulta la guía de migración 0.26 (EN)

Eliminado: Shims parciales para Web APIs en código de servidor

En Astro v2.x, Astro proporcionaba shims parciales para las Web APIs como document o localStorage en el código de servidor. Estos shims a menudo eran incompletos y poco confiables.

Astro v3.0 elimina por completo estos shims parciales. Las Web APIs ya no están disponibles en el código renderizado en el servidor.

¿Qué debo hacer?

Si estás utilizando Web APIs en componentes renderizados en el servidor, deberás hacer que el uso de esas APIs sea condicional o utilizar la directiva client:only.

Eliminado: image de astro:content en el esquema de colecciones de contenido

En Astro v2.x, la API de colecciones de contenido marcó como obsoleta la exportación de image desde astro:content para su uso en los esquemas de colecciones de contenido.

Astro v3.0 elimina por completo esta exportación.

¿Qué debo hacer?

Si estás utilizando el image() obsoleto de astro:content, elimínalo ya que ya no existe. Valida las imágenes a través del ayudante image del esquema en su lugar:

src/content/config.ts

import { defineCollection, z, image } from "astro:content";
import { defineCollection, z } from "astro:content";

defineCollection({
  schema: ({ image }) =>
    z.object({
      image: image(),
   }),
});

Eliminado: Nombres de temas de Shiki pre-0.14

En Astro v2.x, algunos nombres de temas de Shiki fueron cambiados, pero se mantuvieron los nombres originales para mantener la compatibilidad hacia atrás.

Astro v3.0 elimina los nombres originales a favor de los nombres de temas renombrados.

¿Qué debo hacer?

Si tu proyecto utiliza alguno de los temas a continuación, renómbralos con su nombre actualizado:

• material-darker -> material-theme-darker
• material-default -> material-theme
• material-lighter -> material-theme-lighter
• material-ocean -> material-theme-ocean
• material-palenight -> material-theme-palenight

Eliminado: Características class:list

En Astro v2.x, la directiva class:list utilizaba una implementación personalizada inspirada en clsx, con algunas características adicionales como la eliminación de duplicados y el soporte para Set.

Astro v3.0 ahora utiliza clsx directamente para class:list, lo cual no admite la eliminación de duplicados ni valores de tipo Set.

¿Qué debo hacer?

Reemplaza cualquier elemento de tipo Set pasado a la directiva class:list con un simple Array.

src/components/MyAstroComponent.astro

<Component class:list={[
  'a',
  'b',
  new Set(['c', 'd'])
  ['c', 'd']
]} />

Eliminado: pasando class:list como una propiedad

En Astro v2.x, los valores de class:list se enviaban a los componentes a través de Astro.props['class:list'].

En Astro v3.0, los valores de class:list se normalizan a un string antes de ser enviados a los componentes a través de Astro.props['class'].

¿Qué debo hacer?

Elimina cualquier código que espere recibir la propiedad class:list.

src/components/MyAstroComponent.astro

---
import { clsx } from 'clsx';
const { class: className, 'class:list': classList } = Astro.props;
const { class: className } = Astro.props;
---
<div
  class:list={[className, classList]}
  class:list={[className]}
/>

Eliminado: Transformación de kebab-case para variables CSS en camelCase

En Astro v2.x, las variables CSS en formato camelCase pasadas al atributo style eran representadas tanto en camelCase (como se escribían originalmente) como en kebab-case (mantenidas para compatibilidad hacia atrás).

Astro v3.0 elimina la transformación a kebab-case para estos nombres de variables CSS en formato camelCase, y solo se representa la variable CSS camelCase original.

src/components/MyAstroComponent.astro

---
const myValue = "red"
---
<!-- entrada -->
<div style={{ "--myValue": myValue }}></div>

<!-- salida (Astro 2.x) -->
<div style="--my-value:var(--myValue);--myValue:red"></div>
<!-- salida (Astro 3.0) -->
<div style="--myValue:red"></div>

¿Qué debo hacer?

Si estabas confiando en Astro para transformar kebab-case en tus estilos, actualiza tus estilos existentes a camelCase para evitar estilos faltantes. Por ejemplo:

src/components/MyAstroComponent.astro

<style>
  div {
   color: var(--my-value);
   color: var(--myValue);
  }
</style>

Eliminado: Aplanamiento automático del valor de retorno de getStaticPaths()

En Astro v2.x, el valor de retorno de getStaticPaths() se aplanaba automáticamente para permitirte devolver un arreglo de arreglos sin errores.

Astro v3.0 elimina el aplanamiento automático del resultado de getStaticPaths().

¿Qué debo hacer?

Si estás devolviendo un arreglo de arreglos en lugar de un arreglo de objetos (como se espera), ahora debes usar .flatMap y .flat para asegurarte de que estás devolviendo un array plano.

Se proporcionará un mensaje de error indicando que el valor de retorno de getStaticPath() debe ser un arreglo de objetos si necesitas actualizar tu código.

Movido: astro check ahora requiere un paquete externo

En Astro v2.x, astro check estaba incluido en Astro por defecto, y sus dependencias estaban empaquetadas en Astro. Esto resultaba en un paquete más grande, independientemente de si usabas o no astro check. También evitaba que tuvieras control sobre la versión de TypeScript y el Servidor de Lenguaje de Astro que se utilizaba.

Astro v3.0 mueve el comando astro check fuera del núcleo de Astro y ahora requiere un paquete externo @astrojs/check. Además, debes instalar typescript en tu proyecto para poder usar el comando astro check.

¿Qué debo hacer?

Ejecuta el comando astro check después de actualizar a Astro v3.0 y sigue las indicaciones para instalar las dependencias requeridas, o bien, instala manualmente @astrojs/check y typescript en tu proyecto.

Obsoleto: build.excludeMiddleware y build.split

En Astro v2.x, build.excludeMiddleware y build.split se utilizaban para cambiar la forma en que se emitían archivos específicos al usar un adaptador en modo SSR.

Astro v3.0 reemplaza estas opciones de configuración de compilación con nuevas opciones de configuración para adaptadores SSR para realizar las mismas tareas: edgeMiddleware y functionPerRoute.

¿Qué debo hacer?

Actualiza el archivo de configuración de Astro para usar las nuevas opciones en la configuración del adaptador directamente.

astro.config.mjs

import { defineConfig } from "astro/config";
import vercel from "@astrojs/vercel/serverless";

export default defineConfig({
    build: {
      excludeMiddleware: true
    },
    adapter: vercel({
      edgeMiddleware: true
    }),
});

astro.config.mjs

import { defineConfig } from "astro/config";
import netlify from "@astrojs/netlify/functions";

export default defineConfig({
     build: {
        split: true
     },
     adapter: netlify({
        functionPerRoute: true
     }),
});

Obsoleto: markdown.drafts

En Astro v2.x, la configuración markdown.drafts permitía tener páginas en borrador disponibles cuando se ejecutaba el servidor de desarrollo, pero que no se construían en producción.

Astro v3.0 desaconseja esta característica a favor del método de colecciones de contenido para manejar las páginas en borrador mediante filtrado manual, lo que proporciona un mayor control sobre la funcionalidad.

¿Qué debo hacer?

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

Obsoleto: Retornando un objeto simple en los endpoints

En Astro v2.x, los endpoints podían devolver un objeto simple, que se convertiría en una respuesta JSON.

Astro v3.0 desecha este comportamiento en favor de devolver directamente un objeto Response.

¿Qué debo hacer?

Actualiza tus endpoints para devolver directamente un objeto Response.

endpoint.json.ts

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

Si realmente necesitas mantener el formato anterior, puedes usar el objeto ResponseWithEncoding, pero será obsoleto en el futuro.

endpoint.json.ts

export async function GET() {
  return { body: { "title": "Blog de Bob" } };
  return new ResponseWithEncoding({ body: { "title": "Blog de Bob" }});
}

Cambiado por defecto: verbatimModuleSyntax en los ajustes preestablecidos de tsconfig.json

En Astro v2.x, la configuración verbatimModuleSyntax estaba desactivada de forma predeterminada, con su equivalente de TypeScript 4.x importsNotUsedAsValues habilitado en el ajuste preestablecido strict.

En Astro v3.0, verbatimModuleSyntax está habilitado en todos los ajustes preestablecidos.

¿Qué debo hacer?

Esta opción requiere que los tipos se importen utilizando la sintaxis import type.

src/components/MyAstroComponent.astro

---
import { type CollectionEntry, getEntry } from "astro:content";
---

Si bien recomendamos mantenerlo activado y hacer correctamente tus importaciones de tipo con type (como se muestra arriba), puedes desactivarlo estableciendo verbatimModuleSyntax: false en tu archivo tsconfig.json si causa algún problema.

tsconfig.json

{
  "compilerOptions": {
    "verbatimModuleSyntax": false
  }
}

Cambiado por defecto: Puerto 3000

En Astro v2.x, Astro se ejecutaba en el puerto 3000 por defecto.

Astro v3.0 cambia el puerto por defecto a 4321. 🚀

¿Qué debo hacer?

Actualiza cualquier referencia existente a localhost:3000, por ejemplo en tests o en tu README, para reflejar el nuevo puerto localhost:4321.

Cambiado por defecto: import.meta.env.BASE_URL trailingSlash

En Astro v2.x, import.meta.env.BASE_URL agregaba por defecto tu configuración base con una barra diagonal al final, llamada trailingSlash. trailingSlash: "ignore" también agregaba una barra diagonal al final.

En Astro v3.0, ya no se agrega una barra diagonal al final a import.meta.env.BASE_URL de forma predeterminada, ni cuando se establece trailingSlash: "ignore". (El comportamiento existente de base en combinación con trailingSlash: "always" o trailingSlash: "never" no ha cambiado).

¿Qué debo hacer?

Si tu configuración base ya tiene una barra diagonal al final, no es necesario realizar ningún cambio.

Si tu configuración base no tiene una barra diagonal al final, agrega una si deseas preservar el comportamiento anterior por defecto (o trailingSlash: "ignore"):

astro.config.mjs

import { defineConfig } from "astro/config";

export default defineConfig({
  base: 'mi-base',
  base: 'mi-base/',
});

Cambiado por defecto: compressHTML

En Astro v2.x, Astro solamente comprimía tu HTML emitido cuando compressHTML se establecía explícitamente como true. El valor predeterminado era false.

Astro v3.0 ahora comprime automáticamente el HTML emitido por defecto.

¿Qué debo hacer?

Ahora puedes eliminar compressHTML: true de tu configuración, ya que este es el nuevo comportamiento predeterminado.

astro.config.mjs

import { defineConfig } from "astro/config";

export default defineConfig({
  compressHTML: true
})

Ahora debes establecer compressHTML: false para desactivar la compresión de HTML.

Cambiado por defecto: scopedStyleStrategy

En Astro v2.x, el valor predeterminado de scopedStyleStrategy era "where".

Astro v3.0 introduce un nuevo valor por defecto: "attribute". De manera predeterminada, los estilos ahora se aplican utilizando atributos data-*.

¿Qué debo hacer?

Para mantener el ámbito de estilo actual de tu proyecto, actualiza el archivo de configuración al valor predeterminado anterior:

astro.config.mjs

import { defineConfig } from "astro/config";

export default defineConfig({
  scopedStyleStrategy: "where"
})

Cambiado por defecto: inlineStyleSheets

En Astro v2.x, todas las hojas de estilo del proyecto se enviaban por defecto como etiquetas de enlace. Podías elegir insertarlas siempre en etiquetas <style> con la opción "always", o insertar en línea solo las hojas de estilo por debajo de un cierto tamaño con "auto", configurando la propiedad build.inlineStylesheets. La configuración predeterminada era "never".

Astro v3.0 cambia el valor predeterminado de inlineStylesheets a "auto". Las hojas de estilo con un tamaño menor que ViteConfig.build.assetsInlineLimit (predeterminado: 4 KB) se incluyen en línea de manera predeterminada. De lo contrario, los estilos del proyecto se envían en hojas de estilo externas.

¿Qué debo hacer?

Si deseas mantener el comportamiento actual de tu proyecto, establece build.inlineStylesheets en el valor predeterminado anterior, que es "never":

astro.config.mjs

import { defineConfig } from "astro/config";

export default defineConfig({
   build: {
    inlineStylesheets: "never"
  }
})

Cambiado por defecto: Servicio image

En Astro v2.x, Squoosh era el servicio de procesamiento de imágenes predeterminado.

Ahora Astro v3.0 incluye Sharp como el servicio de procesamiento de imágenes predeterminado y en su lugar se proporciona una opción de configuración para usar Squoosh.

¿Qué debo hacer?

Nota

Cuando uses un administrador de paquetes estricto como pnpm, es posible que necesites instalar manualmente Sharp en tu proyecto, aunque sea una dependencia de Astro:

pnpm add sharp

Si prefieres seguir utilizando Squoosh para transformar tus imágenes, actualiza tu configuración con lo siguiente:

astro.config.mjs

import { defineConfig, squooshImageService } from "astro/config";

export default defineConfig({
  image: {
    service: squooshImageService(),
  }
})

Cambiado: Mayúsculas en los métodos de solicitud HTTP

En Astro v2.x, los métodos de solicitud HTTP se escribían utilizando nombres de funciones en minúsculas: get, post, put, all y del.

Astro v3.0 utiliza nombres de funciones en mayúsculas, incluyendo DELETE en lugar de del.

¿Qué debo hacer?

Cambia el nombre de todas las funciones a su equivalente en mayúsculas:

• get a GET
• post a POST
• put a PUT
• all a ALL
• del a DELETE

endpoint.ts

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

Cambiado: Configuración de múltiples frameworks JSX

En Astro v2.x, podías utilizar varias integraciones de frameworks JSX (React, Solid, Preact) en el mismo proyecto sin necesidad de identificar a qué framework pertenecían los archivos.

Ahora en Astro v3.0, es necesario especificar qué framework utilizar para tus archivos mediante las nuevas opciones de configuración de integración include y exclude cuando tienes instaladas múltiples integraciones de framework JSX. Esto permite que Astro admita de manera más eficiente el uso de un solo framework, así como características avanzadas como React Fast Refresh.

¿Qué debo hacer?

Si estás utilizando múltiples frameworks JSX en el mismo proyecto, establece include (y opcionalmente exclude) en un arreglo de archivos y/o carpetas. Puedes utilizar comodines para incluir múltiples rutas de archivo.

Recomendamos colocar los componentes comunes del framework en la misma carpeta (por ejemplo, /components/react/ y /components/solid/) para facilitar la especificación de tus inclusiones, pero esto no es obligatorio:

import { defineConfig } from 'astro/config';
import preact from '@astrojs/preact';
import react from '@astrojs/react';
import svelte from '@astrojs/svelte';
import vue from '@astrojs/vue';
import solid from '@astrojs/solid-js';

export default defineConfig({
  // Habilita varios frameworks para admitir todo tipo de componentes diferentes.
  // ¡No se necesita `include` si solo estás utilizando un solo framework!
  integrations: [
    preact({
      include: ['**/preact/*']
    }),
    react({
      include: ['**/react/*']
    }),
    solid({
      include: ['**/solid/*'],
    }),
  ]
});

Cambiado: Astro.cookies.get(key) puede retornar undefined

En Astro v2.x, Astro.cookies.get(key) siempre devolvería un objeto AstroCookie, incluso si la cookie no existiera. Para verificar su existencia, necesitabas usar Astro.cookies.has(key).

En Astro v3.0, Astro.cookies.get(key) devuelve undefined si la cookie no existe.

¿Qué debo hacer?

Este cambio no romperá ningún código que verifique la existencia del objeto Astro.cookie antes de usar Astro.cookies.get(key), pero ya no es necesario hacerlo.

Puedes eliminar de manera segura cualquier código que utilice has() para verificar si el valor de Astro.cookies es undefined:

if (Astro.cookies.has(id)) {
  const id = Astro.cookies.get(id)!;
}

const id = Astro.cookies.get(id);
if (id) {
}

Cambiado: Ejecutando la CLI de Astro de manera programática.

En Astro v2.x, el punto de entrada del paquete "astro" exportaba y ejecutaba directamente la CLI de Astro. No se recomienda ejecutar Astro de esta manera en la práctica.

Astro v3.0 elimina la CLI del punto de entrada y exporta un nuevo conjunto de APIs experimentales en JavaScript, que incluyen dev(), build(), preview() y sync().

¿Qué debo hacer?

Para ejecutar la CLI de Astro de manera programática, utiliza las nuevas APIs experimentales en JavaScript:

import { dev, build } from "astro";

// Inicia el servidor de desarrollo de Astro
const devServer = await dev();
await devServer.stop();

// Construye tu proyecto de Astro
await build();

Cambiado: Rutas de exportación de puntos de entrada de la API interna de Astro

En Astro v2.x, podías importar las APIs internas de Astro desde astro/internal/* y astro/runtime/server/*.

Astro v3.0 elimina los dos puntos de entrada a favor del punto de entrada existente astro/runtime/*. Además, se ha agregado una nueva exportación astro/compiler-runtime para el código de runtime específico del compilador.

¿Qué debo hacer?

Estos son puntos de entrada para la API interna de Astro y no deberían afectar tu proyecto. Pero si utilizas estos puntos de entrada, actualiza como se muestra a continuación:

import 'astro/internal/index.js';
import 'astro/runtime/server/index.js';

import 'astro/server/index.js';
import 'astro/runtime/server/index.js';

import { transform } from '@astrojs/compiler';

const result = await transform(source, {
  internalURL: 'astro/runtime/server/index.js',
  internalURL: 'astro/compiler-runtime',
  // ...
});

Mejoras de funcionalidades

Actualización de imágenes a la versión 3

astro:assets ya no está detrás de una bandera experimental en Astro v3.0.

<Image /> ahora es un componente incorporado y la integración anterior @astrojs/image ha sido eliminada.

Estos y otros cambios relacionados con el uso de imágenes en Astro pueden provocar cambios incompatibles al actualizar tu proyecto Astro desde una versión anterior.

Por favor, sigue las instrucciones a continuación según corresponda para actualizar un proyecto Astro v2.x a la versión 3.0.

Actualización desde experimental.assets

Si previamente habías activado la bandera experimental para astro:assets, deberás actualizar tu proyecto para Astro v3.0, que ahora incluye las funcionalidades de assets de forma predeterminada.

Eliminar la bandera experimental.assets

Elimina la bandera experimental:

astro.config.mjs

import { defineConfig } from 'astro/config';

export default defineConfig({
  experimental: {
    assets: true
  }
});

Si es necesario, actualiza también tu archivo src/env.d.ts para reemplazar la referencia a astro/client-image por astro/client:

src/env.d.ts

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

Este alias de importación ya no se incluye por defecto con astro:assets. Si estabas usando este alias con los assets experimentales, debes convertirlos a rutas de archivo relativas o crear tus propios alias de importación.

src/pages/posts/post-1.astro

---
import rocket from '~/assets/rocket.png';
import rocket from '../../assets/rocket.png';
---

---

Añadir soporte básico de assets para Cloudflare, Deno, Vercel Edge y Netlify Edge

Astro v3.0 permite que astro:assets funcione sin errores en Cloudflare, Deno, Vercel Edge y Netlify Edge, los cuales no son compatibles con la optimización de imágenes integrada de Astro mediante Squoosh y Sharp. Ten en cuenta que Astro no realiza ninguna transformación ni procesamiento de imágenes en estos entornos. Sin embargo, aún puedes disfrutar de otros beneficios al usar astro:assets, incluyendo la ausencia de desplazamiento acumulativo de diseño (CLS), el atributo alt obligatorio y una experiencia de creación consistente.

Si anteriormente evitaste usar astro:assets debido a estas limitaciones, ahora puedes utilizarlos sin problemas. Puedes configurar el servicio de imágenes sin operaciones (no-op image service) para activar este comportamiento explícitamente:

astro.config.mjs

import { defineConfig } from 'astro/config';

export default defineConfig({
  image: {
    service: {
      entrypoint: 'astro/assets/services/noop'
    }
  }
});

Decide dónde almacenar tus imágenes

Consulta la guía de Imágenes para ayudarte a decidir dónde almacenar tus imágenes. Tal vez quieras aprovechar las nuevas opciones para almacenar tus imágenes gracias a la flexibilidad adicional que ofrece astro:assets. Por ejemplo, ahora se pueden referenciar imágenes relativas desde el directorio src/ de tu proyecto en Markdown, MDX y Markdoc usando la sintaxis estándar de Markdown: ![alt](src).

Actualiza las etiquetas <img> existentes

Anteriormente, importar una imagen devolvía simplemente una string con la ruta de la imagen. Ahora, los assets de imagen importados tienen la siguiente firma:

interface ImageMetadata {
  src: string;
  width: number;
  height: number;
  format: string;
}

Debes actualizar el atributo src de cualquier etiqueta <img> existente** (incluyendo imágenes en componentes de frameworks de interfaz de usuario), y también puedes actualizar otros atributos que ahora están disponibles a partir de la imagen importada.

src/components/MyComponent.astro

---
import rocket from '../images/rocket.svg';
---
<img src={rocket} width="250" height="250" alt="A rocketship in space." />

<img src={rocket.src} width={rocket.width} height={rocket.height} alt="A rocketship in space." />

Actualiza tus archivos Markdown, MDX y Markdoc

Ahora se pueden referenciar imágenes relativas desde el directorio src/ de tu proyecto en archivos Markdown, MDX y Markdoc utilizando la sintaxis estándar de Markdown: ![alt](src).

Esto te permite mover tus imágenes del directorio public/ al directorio src/ de tu proyecto, donde ahora serán procesadas y optimizadas. Las imágenes que ya tengas en public/, así como las imágenes remotas, siguen siendo válidas, pero no serán optimizadas por el proceso de compilación de Astro.

src/pages/posts/post-1.md

# My Markdown Page

<!-- Local images now possible! -->
![A starry night sky.](../../images/stars.png)

<!-- Keep your images next to your content! -->
![A starry night sky.](./stars.png)

Si necesitas más control sobre los atributos de tus imágenes, te recomendamos usar el formato de archivo .mdx, que te permite incluir el componente <Image /> de Astro o una etiqueta <img /> en JSX, además de la sintaxis estándar de Markdown. Utiliza la integración de MDX para añadir soporte para MDX en Astro.

Elimina @astrojs/image

Si estabas utilizando la integración de imágenes en Astro v2.x, completa los siguientes pasos:

1. Elimina la integración @astrojs/image.

   Debes eliminar la integración desinstalándola y luego eliminándola de tu archivo astro.config.mjs.

   astro.config.mjs

   import { defineConfig } from 'astro/config';
   import image from '@astrojs/image';
   
   export default defineConfig({
     integrations: [
       image(),
     ]
   })

2. Actualiza los tipos (si es necesario).

   Si habías configurado tipos especiales para @astrojs/image en src/env.d.ts, es posible que necesites volver a los tipos predeterminados de Astro si tu actualización a la versión 3 no completó este paso automáticamente.

   src/env.d.ts

      /// <reference types="@astrojs/image/client" />
      /// <reference types="astro/client" />

   De manera similar, actualiza el archivo tsconfig.json si es necesario:

   tsconfig.json

     {
       "compilerOptions": {
         "types": ["@astrojs/image/client"]
         "types": ["astro/client"]
       }
     }

3. Migra cualquier componente <Imagen /> existente.

   Cambia todas las declaraciones de import de @astrojs/image/components a astro:assets para poder usar el nuevo componente integrado <Image />.

   Elimina cualquier atributo del componente que no sean propiedades de assets de imagen actualmente admitidas.

   Por ejemplo, aspectRatio ya no es compatible, ya que ahora se infiere automáticamente a partir de los atributos width y height.

   src/components/MyComponent.astro

   ---
   import { Image } from '@astrojs/image/components';
   import { Image } from 'astro:assets';
   import localImage from '../assets/logo.png';
   const localAlt = 'El logo de Astro';
   ---
   
   <Image
     src={localImage}
     width={300}
     aspectRatio="16:9"
     alt={localAlt}
   />

4. Elige un servicio de imágenes predeterminado.

   Sharp es ahora el servicio de imágenes predeterminado utilizado para astro:assets. Si deseas utilizar Sharp, no se requiere ninguna configuración.

   Si prefieres utilizar Squoosh para transformar tus imágenes, actualiza tu configuración con la siguiente opción image.service:

   astro.config.mjs

   import { defineConfig, squooshImageService } from 'astro/config';
   
   export default defineConfig({
     image: {
       service: squooshImageService(),
     },
   });

Actualiza los esquemas de Content Collections (colecciones de contenido).

Ahora puedes declarar una imagen asociada a una entrada de content collections, como la imagen de portada de una publicación de blog, en el frontmatter utilizando su ruta relativa a la carpeta actual.

El nuevo asistente image para content collections te permite validar los metadatos de la imagen usando Zod. Aprende más sobre cómo usar imágenes en content collections.

Cómo manejar las importaciones de imágenes en Astro v3.0

En Astro v3.0, si necesitas conservar el comportamiento anterior de las importaciones de imágenes y requieres una representación en forma de cadena (string) de la URL de la imagen, agrega ?url al final de la ruta de la imagen al importarla. Por ejemplo:

src/pages/blog/MyImages.astro

---
import Sprite from '../assets/logo.svg?url';
---

<svg>
  <use xlink:href={Sprite + '#cart'} />
</svg>

Este enfoque garantiza que obtendrás la URL como una cadena de texto. Ten en cuenta que, durante el desarrollo, Astro utiliza una ruta relativa desde src/, pero al compilar el proyecto, genera rutas con hash como /_astro/cat.a6737dd3.png.

Si prefieres trabajar directamente con el objeto de la imagen, puedes acceder a la propiedad .src. Este método es ideal para tareas como gestionar las dimensiones de la imagen para métricas de Core Web Vitals y evitar el desplazamiento acumulativo del diseño (CLS).

Si estás haciendo la transición al nuevo comportamiento de importación, combinar los métodos ?url y .src podría ser la mejor manera de manejar las imágenes sin inconvenientes.

Actualizar view transitions a la versión 3

Las transiciones de vista ya no están detrás de una bandera experimental en Astro v3.0.

Si no habías activado esta bandera experimental en Astro 2.x, esto no causará ningún cambio incompatible en tu proyecto. La nueva API de transiciones de vista no afecta tu código existente.

Si usabas previamente las transiciones de vista experimentales, puede haber algunos cambios incompatibles al actualizar tu proyecto Astro desde una versión anterior.

Sigue las instrucciones a continuación, según corresponda, para actualizar un proyecto Astro v2.x configurado con experimental.viewTransitions: true a la versión 3.0.

Actualización desde experimental.viewTransitions

Si habías activado anteriormente la bandera experimental para las transiciones de vista, deberás actualizar tu proyecto para Astro v3.0, que ahora permite las transiciones de vista de forma predeterminada.

Eliminar la bandera experimental.viewTransitions

Elimina la bandera experimental:

astro.config.mjs

import { defineConfig } from 'astro/config';

export default defineConfig({
  experimental: {
   viewTransitions: true
  }
});

Actualiza la fuente de importación

El componente <ViewTransitions /> se ha movido de astro:components a astro:transitions. Actualiza la fuente de importación en todas las apariciones dentro de tu proyecto.

src/layouts/BaseLayout.astro

---
import { ViewTransitions } from "astro:components astro:transitions"
---
<html lang="en">
  <head>
    <title>My Homepage</title>
    <ViewTransitions />
  </head>
  <body>
    <h1>Welcome to my website!</h1>
  </body>
</html>

Actualizar directivas transition:animate

Cambiado: El valor morph de la directiva transition:animate ha sido renombrado a initial. Además, esta ya no es la animación por defecto. Si no se especifica ninguna directiva transition:animate, tus animaciones ahora serán por defecto fade.

1. Renombra cualquier animación morph a initial.

   src/components/MyComponent.astro

   <div transition:name="name" transition:animate="morph initial" />

2. Para mantener cualquier animación que previamente usara morph por defecto, añade explícitamente transition:animate="initial" a esas animaciones.

   src/components/MyComponent.astro

   <div transition:name="name" transition:animate="initial" />

3. Puedes eliminar de manera segura cualquier animación configurada explícitamente como fade. Esto es ahora el comportamiento por defecto:

   src/components/MyComponent.astro

   <div transition:name="name" transition:animate="fade" />

Añadido: Astro también admite un nuevo valor para transition:animate, llamado none. Este valor puede ser utilizado en el elemento <html> de una página para desactivar las transiciones animadas de página completa en toda la página. Esto solo anulará el comportamiento de animación predeterminado en elementos de la página que no tengan una directiva de animación. Aún puedes establecer animaciones en elementos individuales y estas animaciones específicas ocurrirán.

4. Ahora puedes desactivar todas las transiciones predeterminadas en una página individual, animando solamente los elementos que utilicen explícitamente una directiva transition:animate:

   <html transition:animate="none">
     <head></head>
     <body>
       <h1>¡Hola Mundo!</h1>
     </body>
   </html>

Actualizar nombres de eventos

El evento astro:load ha sido renombrado a astro:page-load. Renombra todas las instancias en tu proyecto.

src/components/MyComponent.astro

<script>
document.addEventListener('astro:load astro:page-load', runSetupLogic);
</script>

El evento astro:beforeload ha sido renombrado como astro:after-swap. Renombra todas las instancias en tu proyecto.

src/components/MyComponent.astro

<script>
document.addEventListener('astro:beforeload astro:after-swap', setDarkMode);
</script>

Recursos de la comunidad

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

Problemas conocidos

Actualmente no hay problemas conocidos.