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.

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

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

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.