Actualizar a Astro v3

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

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

Actualizar Astro

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

npm

# Upgrade to Astro v3.x
npm install astro@latest

# Example: upgrade React and Tailwind integrations
npm install @astrojs/react@latest @astrojs/tailwind@latest

pnpm

# Upgrade to Astro v3.x
pnpm add astro@latest

# Example: upgrade React and Tailwind integrations
pnpm add @astrojs/react@latest @astrojs/tailwind@latest

Yarn

# Upgrade to Astro v3.x
yarn add astro@latest

# Example: upgrade React and Tailwind integrations
yarn add @astrojs/react@latest @astrojs/tailwind@latest

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

Flags experimentales de Astro v3.0 removidos

Elimina los siguientes flags experimentales de astro.config.mjs:

astro.config.mjs

import { defineConfig } from 'astro/config';

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

Estas funcionalidades ahora están disponibles por defecto:

• View Transitions para transiciones de página animadas e islas persistentes. Consulta los cambios importantes de la API de view transitions y consejos de actualización si estabas usando este flag experimental.
• Una nueva API de servicios de imágenes astro:assets para usar imágenes en Astro, incluyendo un nuevo componente <Image /> y la función getImage(). Por favor lee el consejo detallado de actualización de imágenes hayan o no estado usando este flag experimental para ver cómo podría afectar tu proyecto.

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

Cambios importantes de Astro v3.0

Astro v3.0 incluye algunos 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 v3.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.

Removido: Soporte para Node 16

Node 16 está programado para llegar al fin de su vida útil en septiembre de 2023.

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

¿Qué debo hacer?

Comprueba que tanto tu entorno de desarrollo como tu entorno de despliegue estén usando Node 18.14.1 o superior.

1. Comprueba tu versión local de Node usando:

   node -v

2. Consulta la documentación de tu entorno de despliegue para verificar que soportan Node 18.

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

   .nvmrc

   18.14.1

Removido: Soporte para TypeScript 4

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

Astro v3.0 actualiza los presets de tsconfig.json para soportar solo TypeScript 5.x. Astro ahora asume que usas TypeScript 5.0 (marzo 2023), o que tu editor lo incluye (ej. VS Code 1.77).

¿Qué debo hacer?

Si tienes TypeScript instalado localmente, actualiza a al menos v5.0.

npm install typescript@latest --save-dev

Removido: @astrojs/image

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

Astro v3.0 elimina esta integración del código base por completo. 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. Necesitarás no solo desinstalar la integración sino también actualizar o eliminar cualquier import statement y los componentes <Image /> y <Picture /> existentes. También podrías necesitar configurar un servicio de procesamiento de imágenes preferido por defecto.

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

Migrar a astro:assets también traerá algunas opciones y funcionalidades de imágenes nuevas que podrías querer usar. Consulta el consejo completo de actualización de imágenes v3.0 para todos los detalles!

astro.config.mjs

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

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

Removido: componente <Markdown />

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

Astro v3.0 elimina completamente 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 continuar usando un componente <Markdown /> similar 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 de la integración.

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

Removido: APIs deprecadas de 1.x

En Astro v1.x, Astro deprecó nuestras configuraciones originales así como el soporte de <style global> y <script hoist>. Sin embargo, estos todavía se soportaban por compatibilidad con versiones anteriores.

Astro v3.0 elimina estas APIs deprecadas por completo. Las configuraciones soportadas oficialmente y la sintaxis moderna <style is:global> y <script> deben usarse en su lugar.

¿Qué debo hacer?

Si continúas usando APIs de v1.x, usa las nuevas APIs para cada funcionalidad en su lugar:

• Opciones de configuración deprecadas: Consulta la guía de migración de 0.26
• Tipos de atributos de script/style deprecados: Consulta la guía de migración de 0.26

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

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

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

¿Qué debo hacer?

Si estás usando Web APIs en componentes renderizados en el servidor, necesitarás hacer el uso de esas APIs condicional o usar la directiva de cliente client:only.

Removido: image de astro:content en el schema de content collections

En Astro v2.x, la API de content collections deprecó un export de image desde astro:content para usar en tus schemas de content collections.

Astro v3.0 elimina este export por completo.

¿Qué debo hacer?

Si estás usando el image() deprecado de astro:content, elimínalo ya que esto ya no existe. Valida las imágenes a través de el helper image desde schema 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(),
   }),
});

Removido: nombres de temas Shiki pre-0.14

En Astro v2.x, algunos nombres de temas de Shiki habían sido renombrados, pero los nombres originales se mantuvieron por compatibilidad con versiones anteriores.

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

¿Qué debo hacer?

Si tu proyecto usa alguno de los temas a continuación, renómbralos a 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

Removido: funcionalidades de class:list

En Astro v2.x, la directiva class:list usaba una implementación personalizada inspirada en clsx con algunas funcionalidades extra como deduplicación y soporte de Set.

Astro v3.0 ahora usa clsx directamente para class:list, que no soporta deduplicación ni valores de Set.

¿Qué debo hacer?

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

src/components/MyAstroComponent.astro

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

Removido: pasar class:list como prop

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

Astro v3.0 normaliza los valores de class:list a un string antes de ser enviados a los componentes vía Astro.props['class']

¿Qué debo hacer?

Elimina cualquier código que espere recibir la prop 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]}
/>

Removido: transformación kebab-case para variables CSS camelCase

En Astro v2.x, las variables CSS camelCase pasadas al atributo style se renderizaban tanto en camelCase (como escrito) como en kebab-case (mantenido por compatibilidad con versiones anteriores).

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

src/components/MyAstroComponent.astro

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

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

¿Qué debo hacer?

Si dependías de 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>

Removido: aplanamiento automático del valor de retorno de getStaticPaths()

En Astro v2.x, el valor de retorno de getStaticPaths() se aplanaba automáticamente para permitir retornar un array de arrays sin errores.

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

¿Qué debo hacer?

Si estás retornando un array de arrays en lugar de un array de objetos (como se espera), .flatMap y .flat deberían usarse ahora para asegurar que estás retornando un array plano.

Un mensaje de error indicando que el valor de retorno de getStaticPath() debe ser un array de objetos se mostrará 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 significaba un paquete más grande independientemente de si alguna vez usaste astro check. Esto también te impedía tener control sobre la versión de TypeScript y el Astro Language Server a usar.

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

¿Qué debo hacer?

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

Deprecado: build.excludeMiddleware y build.split

En Astro v2.x, build.excludeMiddleware y build.split se usaban para cambiar cómo se emitían archivos específicos al usar un adapter en modo SSR.

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

¿Qué debo hacer?

Actualiza el archivo de configuración de Astro para usar ahora las nuevas opciones en la configuración del adapter 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
     }),
});

Deprecado: markdown.drafts

En Astro v2.x, la configuración markdown.drafts te permitía tener páginas borrador que estaban disponibles al ejecutar el dev server, pero no se construían en producción.

Astro v3.0 deprecá esta funcionalidad en favor del método de content collections para manejar páginas borrador filtrando manualmente, lo que da más control sobre la funcionalidad.

¿Qué debo hacer?

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.

Deprecado: retornar un objeto simple en endpoints

En Astro v2.x, los endpoints podían retornar un objeto simple, que sería convertido a una respuesta JSON.

Astro v3.0 deprecá este comportamiento en favor de retornar un objeto Response directamente.

¿Qué debo hacer?

Actualiza tus endpoints para retornar un objeto Response directamente.

endpoint.json.ts

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

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

endpoint.json.ts

export async function GET() {
  return { body: { "title": "Bob's blog" } };
  return new ResponseWithEncoding({ body: { "title": "Bob's blog" }});
}

Cambiado por defecto: verbatimModuleSyntax en los presets de tsconfig.json

En Astro v2.x, la configuración verbatimModuleSyntax estaba desactivada por defecto, con su equivalente de TypeScript 4.x importsNotUsedAsValues habilitado en el preset strict.

En Astro v3.0, verbatimModuleSyntax está habilitado en cada preset.

¿Qué debo hacer?

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

src/components/MyAstroComponent.astro

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

Aunque recomendamos mantenerlo activado y hacer correctamente tus importaciones de tipos 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: trailingSlash de import.meta.env.BASE_URL

En Astro v2.x, import.meta.env.BASE_URL añadía tu configuración de base con una trailingSlash por defecto. trailingSlash: "ignore" también añadía una barra diagonal final.

Astro v3.0 ya no añade una barra diagonal final a import.meta.env.BASE_URL por defecto, ni cuando se establece trailingSlash: "ignore". (El comportamiento existente de base en combinación con trailingSlash: "always" o trailingSlash: "never" no cambia.)

¿Qué debo hacer?

Si tu base ya tiene una barra diagonal final, no se necesita ningún cambio.

Si tu base no tiene una barra diagonal final, añade una si deseas preservar el comportamiento por defecto anterior (o de trailingSlash: "ignore"):

astro.config.mjs

import { defineConfig } from "astro/config";

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

Cambiado por defecto: compressHTML

En Astro v2.x, Astro solo comprimía tu HTML emitido cuando compressHTML se establecía explícitamente a true. El valor por defecto era false.

Astro v3.0 ahora comprime el HTML emitido por defecto.

¿Qué debo hacer?

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

astro.config.mjs

import { defineConfig } from "astro/config";

export default defineConfig({
  compressHTML: true
})

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

Cambiado por defecto: scopedStyleStrategy

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

Astro v3.0 introduce un nuevo valor por defecto: "attribute". Por defecto, los estilos ahora se aplican usando atributos data-*.

¿Qué debo hacer?

Para retener el scoping de estilos actual de tu proyecto, actualiza el archivo de configuración al valor por defecto 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 como link tags por defecto. Podías optar por inlinearlas en etiquetas <style> cada vez con "always", o por inlinear solo hojas de estilo por debajo de un cierto tamaño con "auto" estableciendo la configuración build.inlineStylesheets. El valor por defecto era "never".

Astro v3.0 cambia el valor por defecto de inlineStylesheets a "auto". Las hojas de estilo más pequeñas que ViteConfig.build.assetsInlineLimit (por defecto: 4kb) se inlinean por defecto. De lo contrario, los estilos del proyecto se envían en hojas de estilo externas.

¿Qué debo hacer?

Si quieres mantener el comportamiento actual de tu proyecto, establece build.inlineStylesheets al valor anterior por defecto, "never":

astro.config.mjs

import { defineConfig } from "astro/config";

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

Cambiado por defecto: servicio de imágenes

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

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

¿Qué debo hacer?

Nota

Al usar un gestor de paquetes estricto como pnpm, puede que necesites instalar Sharp manualmente en tu proyecto aunque sea una dependencia de Astro:

pnpm add sharp

Si prefieres continuar usando 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/minúsculas en métodos de petición HTTP

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

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

¿Qué debo hacer?

Renombra 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": "Bob's blog" }));
}

Cambiado: Configuración de múltiples frameworks JSX

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

Astro v3.0 ahora requiere que especifiques qué framework usar para tus archivos con las nuevas opciones de configuración de integración include y exclude cuando tienes múltiples integraciones de frameworks JSX instaladas. Esto permite a Astro soportar mejor el uso de un solo framework, así como funcionalidades avanzadas como React Fast Refresh.

¿Qué debo hacer?

Si estás usando múltiples frameworks JSX en el mismo proyecto, establece include (y opcionalmente exclude) a un array de archivos y/o carpetas. Se pueden usar wildcards para incluir múltiples rutas de archivos.

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({
  // Enable many frameworks to support all different kinds of components.
  // No `include` is needed if you are only using a single 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 retornaba un objeto AstroCookie, incluso si la cookie no existía. Para comprobar su existencia, necesitabas usar Astro.cookies.has(key).

Astro v3.0 retorna undefined para Astro.cookies.get(key) si la cookie no existe.

¿Qué debo hacer?

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

Puedes eliminar de forma segura cualquier código que use has() para comprobar 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: ejecutar el CLI de Astro programáticamente

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

Astro v3.0 elimina el CLI del entry point, y exporta un nuevo conjunto de APIs experimentales de JavaScript, incluyendo dev(), build(), preview(), y sync().

¿Qué debo hacer?

Para ejecutar el CLI de Astro programáticamente, usa las nuevas APIs experimentales de JavaScript:

import { dev, build } from "astro";

// Start the Astro dev server
const devServer = await dev();
await devServer.stop();

// Build your Astro project
await build();

Cambiado: rutas de exportación de entry points de la API interna de Astro

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

Astro v3.0 elimina los dos entry points en favor del entry point existente astro/runtime/*. Adicionalmente, se ha añadido un nuevo export astro/compiler-runtime para código de runtime específico del compiler.

¿Qué debo hacer?

Estos son entry points para la API interna de Astro y no deberían afectar tu proyecto. Pero si usas estos entry points, 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',
  // ...
});

Actualizaciones de funcionalidades

Actualizar imágenes a v3

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

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

Estos y otros cambios que acompañan el uso de imágenes en Astro pueden causar algunos cambios importantes al actualizar tu proyecto de Astro desde una versión anterior.

Sigue las instrucciones a continuación según corresponda para actualizar un proyecto de Astro v2.x a v3.0.

Actualizar desde experimental.assets

Si habías habilitado previamente el flag experimental para astro:assets, necesitarás actualizar tu proyecto para Astro v3.0 que ahora incluye las funcionalidades de assets por defecto.

Eliminar el flag experimental.assets

Elimina el flag experimental:

astro.config.mjs

import { defineConfig } from 'astro/config';

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

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

src/env.d.ts

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

Eliminar el alias de importación ~/assets

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

src/pages/posts/post-1.astro

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

Añadir soporte simple 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, que no soportan la optimización de imágenes Squoosh y Sharp integrada de Astro. 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 los otros beneficios de usar astro:assets, incluyendo sin Cumulative Layout Shift (CLS), el atributo alt obligatorio, y una experiencia de authoring consistente.

Si anteriormente evitaste usar astro:assets por estas restricciones, ahora puedes usarlo sin problemas. Puedes configurar el servicio de imágenes no-op para optar explícitamente por este comportamiento:

astro.config.mjs

import { defineConfig } from 'astro/config';

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

Decidir dónde almacenar tus imágenes

Consulta la guía de Images para ayudarte a decidir dónde almacenar tus imágenes. Podrás querer aprovechar las nuevas opciones para almacenar tus imágenes con la flexibilidad añadida que astro:assets aporta. Por ejemplo, las imágenes relativas desde el src/ de tu proyecto ahora pueden referenciarse en Markdown, MDX, y Markdoc usando la sintaxis estándar de Markdown ![alt](src).

Actualizar etiquetas <img> existentes

Anteriormente, importar una imagen retornaba un simple string con la ruta de la imagen. Ahora, los assets de imágenes importados coinciden con la siguiente signature:

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

Debes actualizar el atributo src de cualquier etiqueta <img> existente (incluyendo cualquier imagen en componentes de frameworks UI) y también puedes actualizar otros atributos que ahora están disponibles desde 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

Las imágenes relativas desde el src/ de tu proyecto ahora pueden referenciarse en Markdown, MDX, y Markdoc usando la sintaxis estándar de Markdown ![alt](src).

Esto te permite mover tus imágenes del directorio public/ al src/ de tu proyecto donde ahora serán procesadas y optimizadas. Tus imágenes existentes en public/ e imágenes remotas siguen siendo válidas pero no son optimizadas por el proceso de build 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, recomendamos usar el formato de archivo .mdx, que te permite incluir el componente <Image /> de Astro o una etiqueta <img /> JSX además de la sintaxis Markdown. Usa la integración MDX para añadir soporte para MDX a Astro.

Eliminar @astrojs/image

Si estabas usando 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 removié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 tenías tipos especiales configurados para @astrojs/image en src/env.d.ts, podrías necesitar cambiarlos de vuelta a los tipos por defecto de Astro si tu actualización a v3 no completó este paso por ti.

   src/env.d.ts

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

   Similarmente, actualiza tsconfig.json si es necesario:

   tsconfig.json

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

3. Migra cualquier componente <Image /> existente.

   Cambia todos los import statements de @astrojs/image/components a astro:assets para usar el nuevo componente <Image /> integrado.

   Elimina cualquier atributo del componente que no sea una propiedad de asset de imagen soportada actualmente.

   Por ejemplo, aspectRatio ya no se soporta, ya que ahora se infiere automáticamente 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 = 'The Astro Logo';
   ---
   
   <Image
     src={localImage}
     width={300}
     aspectRatio="16:9"
     alt={localAlt}
   />

4. Elige un servicio de imágenes por defecto.

   Sharp es ahora el servicio de imágenes por defecto usado para astro:assets. Si quieres usar Sharp, no se requiere configuración.

   Si prefieres usar 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 schemas de Content Collections

Ahora puedes declarar una imagen asociada para una entrada de content collections, como la imagen de portada de un post de blog, en tu frontmatter usando su ruta relativa a la carpeta actual.

El nuevo helper 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

Navegando importaciones de imágenes en Astro v3.0

En Astro v3.0, si tienes que preservar el antiguo comportamiento de importación para imágenes y requieres una representación string de la URL de la imagen, añade ?url al final de la ruta de tu 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 asegura que obtienes el string de la URL. Ten en cuenta que durante el desarrollo, Astro usa una ruta src/, pero al construir, genera rutas con hash como /_astro/cat.a6737dd3.png.

Si prefieres trabajar directamente con el objeto de imagen, puedes acceder a la propiedad .src. Este enfoque es mejor para tareas como gestionar las dimensiones de imagen para métricas de Core Web Vitals y prevenir CLS.

Si estás transitando al nuevo comportamiento de importación, combinar los métodos ?url y .src podría ser el método correcto para un manejo de imágenes sin interrupciones.

Actualizar view transitions a v3

Las view transitions ya no están detrás de un flag experimental en Astro v3.0.

Si no habías habilitado este flag experimental en Astro 2.x, esto no causará ningún cambio importante en tu proyecto. La nueva API de View Transitions no tiene efecto en tu código existente.

Si estabas usando view transitions experimentales, puede que haya algunos cambios importantes al actualizar tu proyecto de Astro desde una versión anterior.

Sigue las instrucciones a continuación según corresponda para actualizar un proyecto de Astro v2.x configurado con experimental.viewTransitions: true a v3.0.

Actualizar desde experimental.viewTransitions

Si habías habilitado previamente el flag experimental para view transitions, necesitarás actualizar tu proyecto para Astro v3.0 que ahora permite view transitions por defecto.

Eliminar el flag experimental.viewTransitions

Elimina el flag experimental:

astro.config.mjs

import { defineConfig } from 'astro/config';

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

Actualizar la fuente de importación

El componente <ViewTransitions /> ha sido movido de astro:components a astro:transitions. Actualiza la fuente de importación en todas las ocurrencias 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 transition:animate ha sido renombrado a initial. Además, este 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 anteriormente usaba morph por defecto, añade explícitamente transition:animate="initial"

   src/components/MyComponent.astro

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

3. Puedes eliminar de forma segura cualquier animación establecida explícitamente a fade. Este es ahora el comportamiento por defecto:

   src/components/MyComponent.astro

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

Añadido: Astro también soporta un nuevo valor de transition:animate, none. Este valor puede usarse en el elemento <html> de una página para deshabilitar las transiciones animadas de página completa en una página entera. Esto solo sobrescribirá el comportamiento de animación por defecto en los elementos de la página sin una directiva de animación. Aún puedes establecer animaciones en elementos individuales, y estas animaciones específicas se ejecutarán.

4. Ahora puedes deshabilitar todas las transiciones por defecto en una página individual, animando solo los elementos que usan explícitamente una directiva transition:animate:

   <html transition:animate="none">
     <head></head>
     <body>
       <h1>Hello world!</h1>
     </body>
   </html>

Actualizar nombres de eventos

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

src/components/MyComponent.astro

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

El evento astro:beforeload ha sido renombrado a astro:after-swap. Renombra todas las ocurrencias 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 añade un enlace abajo!

Problemas conocidos

Actualmente no hay problemas conocidos.