Actualizar a Astro v6

Esta guía te ayudará a migrar de Astro v5 a Astro v6.

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

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

Actualizar Astro

Actualiza la versión de Astro de tu proyecto a la última versión usando tu gestor de paquetes:

npm

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

pnpm

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

Yarn

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

También puedes actualizar tus integraciones de Astro manualmente si es necesario, y también podrías necesitar actualizar otras dependencias en tu proyecto.

¿Necesitas continuar?

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

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

Astro v6.0 incluye posibles cambios importantes, así como la remoción y deprecación de algunas funcionalidades.

Si tu proyecto no funciona como se espera después de actualizar a v6.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 de Astro para las notas de versión completas.

Actualizaciones de dependencias

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

Node 22

PR de implementación: feat!: drop node 18 and 20 (#14427)

Node 18 alcanzó su End of Life en marzo de 2025 y Node 20 está programado para alcanzar su End of Life en abril de 2026.

Astro v6.0 elimina el soporte para Node 18 y Node 20 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 22.12.0 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 22.

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

   .nvmrc

   22.12.0

Vite 7.0

PR de implementación: feat: update vite (#14445)

Astro v6.0 actualiza a Vite v7.0 como servidor de desarrollo y bundler de producción.

¿Qué debo hacer?

Si estás usando plugins, configuración, o APIs específicas de Vite, consulta la guía de migración de Vite para sus cambios importantes y actualiza tu proyecto según sea necesario.

Usar el helper getViteConfig() de Astro requiere al menos Vitest v3.2 o v4.1 beta 5.

Vite Environment API

PR de implementación: feat: integrate vite environments (#14306)

Astro v6.0 introduce cambios significativos en cómo Astro gestiona diferentes entornos de runtime (cliente, servidor y prerender) después de un refactor interno para usar la nueva Environments API de Vite.

¿Qué debo hacer?

Los mantenedores de integraciones y adapters deben prestar especial atención a los cambios que afectan estas partes de la Integration API y la Adapter API (detalles completos incluidos a continuación con otros cambios importantes de estas APIs):

• Ruta de configuración del nombre de archivo de salida de Rollup
• patrones de acceso a hooks de integración y HMR
• estructura de SSRManifest
• generación de rutas con RouteData
• rutas con signos de porcentaje percent-encoded (ej. %25)
• módulo virtual astro:ssr-manifest
• NodeApp desde astro/app/node
• loadManifest() y loadApp() desde astro/app/node
• createExports() y start()

Zod 4

Astro v6.0 actualiza a Zod 4, una actualización importante de dependencia que puede requerir cambios en los schemas personalizados de Zod en tu proyecto.

¿Qué debo hacer?

Si tienes schemas personalizados de Zod en tu content.config.ts u otros archivos de configuración, necesitarás actualizarlos para Zod 4. Consulta la guía de migración de Zod para los cambios detallados en la API de Zod.

Notablemente, muchos formatos de string() han sido deprecados (ej. z.string().email(), z.string.url()), y sus APIs se han movido al namespace de nivel superior z. Podrías necesitar actualizar cómo validas la entrada de formularios para tus Astro Actions:

src/actions/index.ts

email: z.string().email(),
email: z.email(),

Adicionalmente, Zod ha hecho algunos cambios en el manejo de mensajes de error y ha eliminado el soporte para un errorsMap personalizado que era útil para redefinir o traducir tus mensajes de error. Podrías necesitar actualizar cualquier mensaje de error personalizado:

src/actions/index.ts

z.string().min(5, { message: "Too short." });
z.string().min(5, { error: "Too short." });

Además, si usas .default() con transforms, podrías necesitar actualizar tus schemas. En Zod 4, los valores por defecto deben coincidir con el tipo de salida (después de los transforms), no con el tipo de entrada. El valor por defecto cortocircuita el parsing cuando la entrada es undefined:

src/content.config.ts

import { z } from 'astro/zod';

const blog = defineCollection({
  schema: z.object({
    // Zod 3: default matched input type (string)
    views: z.string().transform(Number).default("0"),
    // Zod 4: default must match output type (number)
    views: z.string().transform(Number).default(0),
  })
});

Para el comportamiento antiguo donde los valores por defecto se parsean, usa el nuevo método .prefault().

Estos son solo algunos de los muchos cambios al actualizar de Zod 3 a Zod 4. Si encuentras algún problema con tus schemas de Zod después de actualizar a Astro 6, por favor consulta el changelog de Zod 4 para guía de actualización completa.

Adicionalmente, un codemod de la comunidad, que puede potencialmente automatizar algunos de estos cambios al migrar de Zod 3 a Zod 4, también está disponible.

Puedes asegurar que estás usando la misma versión de Zod que Astro usa internamente importando Zod desde astro/zod.

import { z } from 'astro/zod';

Ver más sobre el módulo astro/zod.

Shiki 4.0

PR de implementación: chore(deps): update shiki to v4 (#15726)

Astro v6.0 actualiza a Shiki v4.0 para el resaltado de sintaxis.

¿Qué debo hacer?

Si estás usando APIs específicas de Shiki, consulta la guía de migración de Shiki para sus cambios importantes y actualiza tu proyecto según sea necesario.

Integraciones oficiales de Astro

Todos los adapters de servidor oficiales de Astro también se han actualizado a una nueva versión major para acompañar la actualización a Vite v7.0 con la Environment API de Vite como servidor de desarrollo y bundler de producción.

En particular, el adapter de Cloudflare de Astro ha experimentado cambios significativos, y se esperan cambios importantes en tu configuración existente de Cloudflare.

Consulta las instrucciones de actualización del adapter de Cloudflare para guía de migración detallada.

¿Qué debo hacer?

Si estás usando un adapter de Astro para renderizado bajo demanda u otras funcionalidades específicas de plataforma, por favor consulta el changelog de tu adapter específico para guía de actualización:

• @astrojs/cloudflare CHANGELOG
• @astrojs/netlify CHANGELOG
• @astrojs/node CHANGELOG
• @astrojs/vercel CHANGELOG

Legacy

Las siguientes funcionalidades ahora se consideran legacy. Deberían funcionar normalmente pero ya no se recomiendan y están en modo mantenimiento. No recibirán futuras mejoras y la documentación no se actualizará. Estas funcionalidades eventualmente serán deprecadas y luego removidas por completo.

Legacy: compatibilidad con versiones anteriores de content collections

En Astro 5.x, los proyectos podían retrasar la actualización a la nueva Content Layer API introducida para content collections debido a alguna compatibilidad automática con versiones anteriores existente que no estaba previamente detrás de un flag. Esto significaba que era posible actualizar de Astro 4 a Astro 5 sin actualizar tus content collections, incluso si no habías habilitado el flag legacy.collections. Los proyectos continuarían compilando, y no se mostrarían errores ni advertencias.

Astro v6.0 elimina este soporte automático de content collections legacy, junto con el flag legacy.collections. Todas las content collections deben ahora usar la Content Layer API introducida en Astro v5.0 que potencia todas las content collections.

¿Qué debo hacer?

Si experimentas errores de content collections después de actualizar a v6, comprueba tu proyecto para cualquier funcionalidad legacy removida que pueda necesitar actualización a la Content Layer API.

Consulta la guía de actualización de Astro v5 para instrucciones detalladas sobre cómo actualizar las colecciones legacy a la nueva Content Layer API.

Si no puedes actualizar inmediatamente, puedes habilitar el flag legacy.collectionsBackwardsCompat como un helper temporal de migración:

astro.config.mjs

export default defineConfig({
  legacy: {
    collectionsBackwardsCompat: true,
  },
});

Este flag preserva algunas funcionalidades legacy de content collections de v4:

• Soporta el archivo de configuración legacy src/content/config.ts
• Soporta type: 'content' y type: 'data' sin loaders
• Preserva la API de entrada legacy: entry.slug y entry.render()
• Usa IDs de entrada basados en rutas en lugar de IDs basados en slug

Este es un helper temporal de migración. Migra tus colecciones a la Content Layer API tan pronto como sea posible, luego deshabilita este flag.

Deprecado

Las siguientes funcionalidades deprecadas ya no se soportan y ya no se documentan. Actualiza tu proyecto en consecuencia.

Algunas funcionalidades deprecadas pueden continuar funcionando temporalmente hasta que sean completamente removidas. Otras pueden silenciosamente no tener efecto, o lanzar un error pidiéndote que actualices tu código.

Deprecado: Astro en getStaticPaths()

PR de implementación: feat: deprecate Astro in getStaticPaths (#14432)

En Astro 5.x, era posible acceder a un objeto Astro dentro de getStaticPaths(). Sin embargo, a pesar de estar tipado igual que el objeto Astro accesible en el frontmatter, este objeto solo tenía las propiedades site y generator. Esto podía llevar a confusión sobre qué propiedades del objeto Astro estaban disponibles dentro de getStaticPaths().

Astro 6.0 deprecá este objeto para getStaticPaths() para evitar confusión y mejora el manejo de errores al intentar acceder a valores de Astro que no están disponibles. Usar Astro.site o Astro.generator dentro de getStaticPaths() ahora registrará una advertencia de deprecación, y acceder a cualquier otra propiedad lanzará un error específico con un mensaje útil. En una futura versión major, este objeto será removido por completo, y acceder a Astro.site o Astro.generator también lanzará un error.

¿Qué debo hacer?

Actualiza tu función getStaticPaths() si estabas intentando acceder a cualquier propiedad de Astro dentro de su scope. Elimina Astro.generator por completo, y reemplaza todas las ocurrencias de Astro.site con import.meta.env.SITE:

src/pages/blog/[slug].astro

---
import { getPages } from "../../../utils/data";

export async function getStaticPaths() {
  console.log(Astro.generator);
  return getPages(Astro.site);
  return getPages(import.meta.env.SITE);
}
---

Lee más sobre las variables de entorno integradas como import.meta.env.SITE que son accesibles al usar getStaticPaths() para generar rutas estáticas dinámicamente.

Deprecado: import.meta.env.ASSETS_PREFIX

PR de implementación: feat: deprecate import.meta.env.ASSETS_PREFIX (#14461)

En Astro 5.x, era posible acceder a build.assetsPrefix en tu configuración de Astro a través de la variable de entorno integrada import.meta.env.ASSETS_PREFIX. Sin embargo, Astro v5.7.0 introdujo el módulo virtual astro:config para exponer una versión no exhaustiva, serializable y type-safe de la configuración de Astro que incluía acceso a build.assetsPrefix directamente. Esto se convirtió en la forma preferida de acceder al prefijo para los enlaces de assets generados por Astro cuando estaba configurado, aunque la variable de entorno aún existía.

Astro 6.0 deprecá esta variable en favor de build.assetsPrefix del módulo astro:config/server.

¿Qué debo hacer?

Reemplaza cualquier ocurrencia de import.meta.env.ASSETS_PREFIX con el import de build.assetsPrefix desde astro:config/server. Este es un reemplazo directo para proporcionar el valor existente, y no deberían ser necesarios otros cambios en tu código:

import { someLogic } from "./utils"
import { build } from "astro:config/server"

someLogic(import.meta.env.ASSETS_PREFIX)
someLogic(build.assetsPrefix)

Lee más sobre el módulo virtual astro:config.

Deprecado: astro:schema y z desde astro:content

PR de implementación: feat!: consolidate zod export (#14923)

En Astro 5.x, astro:schema se introdujo como un alias de astro/zod. z también se exportaba desde astro:content por conveniencia. Sin embargo, esto ocasionalmente creaba confusión para los usuarios que no estaban seguros de desde dónde deberían importar.

Astro 6.0 deprecá astro:schema y z desde astro:content en favor de astro/zod.

¿Qué debo hacer?

Reemplaza cualquier ocurrencia de astro:schema con astro/zod:

import { z } from "astro:schema"
import { z } from "astro/zod"

Elimina z de tus imports de astro:content e importa z por separado desde astro/zod en su lugar:

src/content.config.ts

import { defineCollection, z } from "astro:content"
import { defineCollection } from "astro:content"
import { z } from "astro/zod"

Ver más sobre definir schemas de colección con Zod.

Deprecado: internos expuestos de astro:transitions

PR de implementación: feat!: deprecate transitions exports (#14989)

En Astro 5.x, algunos internos se exportaban desde astro:transitions y astro:transitions/client que no estaban destinados a ser expuestos para uso público.

Astro 6.0 elimina las siguientes funciones y tipos como exports de los módulos virtuales astro:transitions y astro:transitions/client. Estos ya no pueden ser importados en los archivos de tu proyecto:

• createAnimationScope()
• isTransitionBeforePreparationEvent()
• isTransitionBeforeSwapEvent()
• TRANSITION_BEFORE_PREPARATION
• TRANSITION_AFTER_PREPARATION
• TRANSITION_BEFORE_SWAP
• TRANSITION_AFTER_SWAP
• TRANSITION_PAGE_LOAD

¿Qué debo hacer?

Elimina cualquier ocurrencia de createAnimationScope():

import { createAnimationScope } from 'astro:transitions';

Actualiza cualquier ocurrencia de los otros exports deprecados:

import {
  isTransitionBeforePreparationEvent,
  TRANSITION_AFTER_SWAP,
} from 'astro:transitions/client';

console.log(isTransitionBeforePreparationEvent(event));
console.log(event.type === 'astro:before-preparation');

console.log(TRANSITION_AFTER_SWAP);
console.log('astro:after-swap');

Aprende más sobre todas las utilidades disponibles en la Referencia de la View Transitions Router API.

Deprecado: signature de string del session driver

PR de implementación: feat(sessions): drivers (#15006)

En Astro 5.x, se podía proporcionar cualquier nombre de unstorage provider o un entrypoint personalizado para definir un session driver, y las opciones también se proporcionaban directamente a la configuración de session. Sin embargo, sentimos que esta API era limitada e inconsistente con otras partes de la configuración de Astro.

Astro 6.0 deprecá la signature de string del driver y las opciones en favor de una nueva forma de objeto.

¿Qué debo hacer?

Actualiza tu configuración de session para usar el sessionDrivers recién exportado:

astro.config.mjs

import { defineConfig } from 'astro/config'
import { defineConfig, sessionDrivers } from 'astro/config'

export default defineConfig({
  session: {
    driver: 'redis',
    options: {
      url: process.env.REDIS_URL
    },
    driver: sessionDrivers.redis({
      url: process.env.REDIS_URL
    }),
    cookie: {
      secure: true
    },
    ttl: 3600
  }
})

Aprende más sobre los session drivers disponibles.

Deprecado: NodeApp desde astro/app/node (Adapter API)

PR de implementación: feat: deprecate NodeApp (#15535)

En Astro 5.x, los adapters podían implementar su server entrypoint usando App para requests/responses web estándar, o NodeApp para requests/responses de node.

Astro 6.0 deprecá NodeApp en favor de createApp() y nuevas utilidades: createRequest() y writeResponse(). Esto permite una API más consistente mientras preserva las mismas funcionalidades de antes. También deprecá el tipo NodeAppHeadersJson.

¿Qué debo hacer?

Si has construido un adapter, actualiza cualquier uso de NodeApp con createApp():

my-adapter/server.js

import { NodeApp } from 'astro/app/node';

export function createExports(manifest) {
  const app = new NodeApp(manifest);

  const handler = async (req, res) => {
    const response = await app.render(req);
    await NodeApp.writeResponse(response, res);
  };

  return { handler };
}
import { createApp } from 'astro/app/entrypoint';
import { createRequest, writeResponse } from 'astro/app/node';

const app = createApp();

export const handler = async (req, res) => {
  const request = createRequest(req);
  const response = await app.render(request);
  await writeResponse(response, res);
}

Aprende más sobre el módulo astro/app/node.

Deprecado: loadManifest() y loadApp() desde astro/app/node (Adapter API)

PR de implementación: feat: deprecate NodeApp (#15535)

En Astro 5.x, astro/app/node exponía las utilidades loadManifest() y loadApp() para permitir cargar el manifest SSR o una instancia de NodeApp desde una instancia de URL. Sin embargo, estas no estaban documentadas y ya no son el uso recomendado con la Adapter API de v6.

Astro 6.0 deprecá ambas funciones.

¿Qué debo hacer?

Si has construido un adapter, elimina loadManifest() y reemplaza loadApp() por createApp():

my-adapter/server.js

import { loadManifest, loadApp, NodeApp } from 'astro/app/node';

const manifest = await loadManifest(new URL(import.meta.url));
const app1 = new NodeApp(loadManifest);
const app2 = await loadApp(new URL(import.meta.url));
import { createApp } from 'astro/app/entrypoint';

const app = createApp();

Aprende más sobre el módulo astro/app/entrypoint.

Deprecado: createExports() y start() (Adapter API)

PR de implementación: feat: improve naming of new adapter api (#15461)

En Astro 5.x, los adapters tenían que proporcionar los exports requeridos por el host en su server entrypoint usando una función createExports() antes de pasarlos a setAdapter() como una lista de exports.

Astro 6.0 introduce una forma más simple pero más potente de crear server entrypoints. Esto depende de pasar una nueva opción entrypointResolution: "auto" a setAdapter().

Sin embargo, para compatibilidad con versiones anteriores con adapters existentes, el valor por defecto de entrypointResolution ("explicit") imita el comportamiento de la API de Astro 5.x. Esto significa que tus adapters pueden continuar funcionando hasta que puedas migrar completamente tu adapter al valor auto, como se muestra a continuación.

Ten en cuenta que entrypointResolution: "explicit" (manteniendo el comportamiento de la API de v5) se considera uso deprecado, pero la opción se ha proporcionado para que no se requiera un cambio inmediato en tu adapter y para dar tiempo a los autores de adapters para actualizar. Esta opción será removida en una futura versión major en favor de que todos los adapters usen entrypointResolution: "auto".

¿Qué debo hacer?

Si eres un autor de adapter con un repositorio público e incluyes la keyword astro-adapter en tu package.json, el equipo central de Astro intentará hacer un PR a tu repositorio directamente para ayudarte a migrar tu código si aún no has seguido los pasos a continuación.

Si estás viendo advertencias porque estás usando un adapter de la comunidad que aún no se ha actualizado, por favor contacta directamente al autor del adapter para informarle. En última instancia, es su responsabilidad actualizar sus adapters. También puedes informar al equipo central de Astro en el canal #integrations de nuestro Discord e intentaremos ayudar al autor del adapter a actualizar.

Si has construido un adapter, sigue estos pasos para eliminar el comportamiento legacy de v5:

1. Actualiza tu setAdapter(): establece entrypointResolution: "auto", elimina exports y args

   my-adapter.mjs

   setAdapter({
     // ...
     entrypointResolution: 'auto',
     exports: ['handler'],
     args: { assets: config.build.assets }
   })

2. Actualiza tu server entrypoint para proporcionar cualquier export requerido sin createExports():

   my-adapter/server.js

   import { App } from 'astro/app';
   
   export function createExports(manifest) {
     const app = new App(manifest);
   
     const handler = (event, context) => {
       // ...
     };
   
     return { handler };
   }
   import { createApp } from 'astro/app/entrypoint';
   
   const app = createApp();
   
   export const handler = (event, context) => {
     // ...
   }

3. Si tu adapter proporciona una función start(), actualiza tu server entrypoint para llamar al código directamente:

   my-adapter/server.js

   import { App } from 'astro/app';
   
   export function start(manifest) {
     const app = new App(manifest);
   
     addEventListener('fetch', event => {
       // ...
     });
   }
   import { createApp } from 'astro/app/entrypoint';
   
   const app = createApp();
   
   addEventListener('fetch', event => {
     // ...
   });

4. Si dependías de args, crea un módulo virtual para pasar la configuración del build time e impórtalos desde el módulo virtual en su lugar:

   my-adapter/server.js

   export function createExports(manifest, { assets }) {
     // ...
   }
   import { assets } from 'virtual:@example/my-adapter:config';

Aprende más sobre la Adapter API.

Removido

Las siguientes funcionalidades han sido ahora enteramente removidas del código base y ya no se pueden usar. Algunas de estas funcionalidades pueden haber continuado funcionando en tu proyecto incluso después de su deprecación. Otras pueden haber silenciosamente no tenido efecto.

Los proyectos que ahora contienen estas funcionalidades removidas no podrán construirse, y ya no habrá documentación de soporte pidiéndote que elimines estas funcionalidades.

Removido: content collections legacy

PR de implementación: fix: remove legacy content collections (#14407)

En Astro 5.x, aún era posible usar la Content Collections API original introducida por primera vez en Astro v2.0, ya sea a través de un flag de configuración legacy o mediante compatibilidad con versiones anteriores integrada. Estos métodos te permitían actualizar a Astro v5 incluso si aún no estabas listo o no podías actualizar tus content collections existentes a las impulsadas por la nueva Content Layer API.

Astro v6.0 elimina por completo este soporte de Content Collections API previamente deprecado, incluyendo el flag legacy.collections y alguna compatibilidad con versiones anteriores existente que no estaba previamente detrás de un flag. Todas las content collections deben ahora usar la Content Layer API introducida en Astro v5.0 que potencia todas las content collections. No hay soporte de compatibilidad con versiones anteriores disponible.

¿Qué debo hacer?

Si habías habilitado previamente el flag legacy, debes eliminarlo.

astro.config.mjs

import { defineConfig } from 'astro/config';

export default defineConfig({
  legacy: {
    collections: true,
  }
})

Adicionalmente, si no actualizaste tus colecciones para Astro v5.0, asegúrate de que tus content collections estén completamente actualizadas para la nueva API.

Astro v5.x incluía alguna compatibilidad automática con versiones anteriores para permitir que las content collections continuaran funcionando incluso si no se habían actualizado para usar la nueva API. Por lo tanto, tus colecciones de v5 pueden contener una o más funcionalidades legacy que necesitan actualización a la API más nueva para v6, incluso si tu proyecto no tenía errores previamente.

Si tienes errores de content collections o advertencias después de actualizar a v6, usa la siguiente lista para ayudarte a identificar y actualizar cualquier funcionalidad legacy que pueda existir en tu código.

Si tienes…

ningún archivo de configuración de content collections

Create src/content.config.ts and define tus colecciones in it.

un archivo de configuración ubicado en src/content/config.ts / (LegacyContentConfigError)

Rename and move this file to src/content.config.ts

una colección que no define un loader / (ContentCollectionMissingALoaderError)

Importa el loader glob() integrado de Astro y define el pattern y base para las entradas de tu colección:

src/content.config.ts

import { defineCollection } from 'astro:content';
import { z } from 'astro/zod';
import { glob } from 'astro/loaders';

const blog = defineCollection({
  loader: glob({ pattern: '**/[^_]*.{md,mdx}', base: "./src/data/blog" }),
  schema: z.object({
    title: z.string(),
    description: z.string(),
    pubDate: z.coerce.date(),
    updatedDate: z.coerce.date().optional(),
  }),
});

una colección que define un tipo de colección (type: 'content' o type: 'data') / (ContentCollectionInvalidTypeError)

There are no longer different types of collections. This must be deleted from your collection definition.

src/content.config.ts

import { defineCollection } from 'astro:content';
import { z } from 'astro/zod';
import { glob } from 'astro/loaders';

const blog = defineCollection({
  // For content layer you no longer define a `type`
  type: 'content',
  loader: glob({ pattern: '**/[^_]*.{md,mdx}', base: "./src/data/blog" }),
  schema: z.object({
    title: z.string(),
    description: z.string(),
    pubDate: z.coerce.date(),
    updatedDate: z.coerce.date().optional(),
  }),
});

métodos de consulta de colecciones legacy getDataEntryById() y getEntryBySlug() / (GetEntryDeprecationError)

Replace both methods with getEntry().

métodos de consulta y renderizado de colecciones legacy que dependen de una propiedad slug / (ContentSchemaContainsSlugError)

Previously, the id was based on the filename, and there was a slug property that could be used in a URL. Now the CollectionEntry id is a slug. If you need access to the filename (previously available as the id), use the filePath property. Replace instances of slug with id:

src/pages/[slug].astro

---
export async function getStaticPaths() {
  const posts = await getCollection('blog');
  return posts.map((post) => ({
    params: { slug: post.slug },
    params: { slug: post.id },
    props: post,
  }));
}
---

contenido renderizado usando entry.render()

Collection entries no longer have a render() method. Instead, import the render() function from astro:content and use render(entry):

src/pages/index.astro

---
import { getEntry, render } from 'astro:content';

const post = await getEntry('pages', 'homepage');

const { Content, headings } = await post.render();
const { Content, headings } = await render(post);
---
<Content />

Consulta la guía de actualización de Astro v5 para guía previa sobre compatibilidad con versiones anteriores de colecciones legacy en Astro v5 e instrucciones paso a paso completas para actualizar colecciones legacy a la nueva Content Layer API.

Removido: componente <ViewTransitions />

PR de implementación: Remove deprecated ViewTransitions component (#14400)

En Astro 5.0, el componente <ViewTransitions /> fue renombrado a <ClientRouter /> para aclarar el rol del componente. El nuevo nombre hace más claro que las funcionalidades que obtienes del componente de enrutamiento <ClientRouter /> de Astro son ligeramente diferentes del router MPA nativo basado en CSS. Sin embargo, una versión deprecada del componente <ViewTransitions /> aún existía y podía funcionar en Astro 5.x.

Astro 6.0 elimina el componente <ViewTransitions /> por completo y ya no puede ser usado en tu proyecto. Actualiza al componente <ClientRouter /> para continuar usando estas funcionalidades.

¿Qué debo hacer?

Reemplaza todas las ocurrencias del import y componente ViewTransitions con ClientRouter:

src/layouts/MyLayout.astro

import { ViewTransitions } from 'astro:transitions';
import { ClientRouter } from 'astro:transitions';

<html>
  <head>
    ...
    <ViewTransitions />
    <ClientRouter />
  </head>
</html>

Lee más sobre view transitions y enrutamiento del lado del cliente en Astro.

Removido: emitESMImage()

PR de implementación: feat!: remove emitESMImage() (#14426)

En Astro 5.6.2, la función emitESMImage() fue deprecada en favor de emitImageMetadata(), que elimina dos argumentos deprecados que no estaban destinados a ser expuestos para uso público: _watchMode y experimentalSvgEnabled.

Astro 6.0 elimina emitESMImage() por completo. Actualiza a emitImageMetadata() para mantener tu comportamiento actual.

¿Qué debo hacer?

Reemplaza todas las ocurrencias de emitESMImage() con emitImageMetadata() y elimina los argumentos no usados:

import { emitESMImage } from 'astro/assets/utils';
import { emitImageMetadata } from 'astro/assets/utils';

const imageId = '/images/photo.jpg';
const result = await emitESMImage(imageId, false, false);
const result = await emitImageMetadata(imageId);

Lee más sobre emitImageMetadata().

Removido: Astro.glob()

PR de implementación: feat!: remove Astro.glob (#14421)

En Astro 5.0, Astro.glob() fue deprecado en favor de usar getCollection() para consultar tus colecciones, y import.meta.glob() para consultar otros archivos fuente en tu proyecto.

Astro 6.0 elimina Astro.glob() por completo. Actualiza a import.meta.glob() para mantener tu comportamiento actual.

¿Qué debo hacer?

Reemplaza todo el uso de Astro.glob() con import.meta.glob(). Ten en cuenta que import.meta.glob() ya no retorna un Promise, así que podrías tener que actualizar tu código en consecuencia. No deberías requerir ninguna actualización a tus glob patterns.

src/pages/blog.astro

---
const posts = await Astro.glob('./posts/*.md');
const posts = Object.values(import.meta.glob('./posts/*.md', { eager: true }));
---

{posts.map((post) => <li><a href={post.url}>{post.frontmatter.title}</a></li>)}

Donde sea apropiado, considera usar content collections para organizar tu contenido, que tiene sus propias funciones de consulta más nuevas y con mejor rendimiento.

También podrías querer considerar usar paquetes glob de NPM, como fast-glob.

Aprende más sobre importar archivos con import.meta.glob.

Removido: internos expuestos de astro:actions

PR de implementación: refactor: cleanup public actions API (#14844)

En Astro 5.x, algunos internos se exportaban desde astro:actions que no estaban destinados a ser expuestos para uso público.

Astro 6.0 elimina las siguientes funciones, clases y tipos como exports del módulo virtual astro:actions. Estos ya no pueden ser importados en los archivos de tu proyecto:

• ACTION_ERROR_CODES
• ActionInputError
• appendForwardSlash
• astroCalledServerError
• callSafely
• deserializeActionResult
• formDataToObject
• getActionQueryString
• serializeActionResult
• type Actions
• type ActionAccept
• type AstroActionContext
• type SerializedActionResult

¿Qué debo hacer?

Reemplaza todos los imports de serializeActionResult() y deserializeActionResult() con getActionContext(). Estos dos métodos ahora están disponibles a través de getActionContext():

src/middleware.ts

import { defineMiddleware } from 'astro:middleware';
import { serializeActionResult, deserializeActionResult } from 'astro:actions';
import { getActionContext } from 'astro:actions';

export const onRequest = defineMiddleware(async (context, next) => {
  const { serializeActionResult, deserializeActionResult } = getActionContext(context);
  // ...
});

Elimina cualquier ocurrencia de los otros exports removidos:

import {
  ACTION_ERROR_CODES,
  ActionInputError,
  appendForwardSlash,
  astroCalledServerError,
  callSafely,
  formDataToObject,
  getActionQueryString,
  type Actions,
  type ActionAccept,
  type AstroActionContext,
  type SerializedActionResult,
} from 'astro:actions';

Aprende más sobre todas las utilidades disponibles en la Referencia de la Actions API.

Removido: Percent-Encoding en rutas

PR de implementación: feat: integrate vite environments (#14306)

En Astro 5.x, era posible incluir un signo de porcentaje percent-encoded (%25) en los nombres de archivo.

Astro 6.0 elimina el soporte para los caracteres %25 en los nombres de archivo por razones de seguridad. Esta restricción previene elusiones de seguridad basadas en codificación donde %25 se decodifica a %, potencialmente llevando a secuencias de codificación ambiguas o inválidas.

¿Qué debo hacer?

Si tienes archivos de ruta con %25 en el nombre del archivo, renómbralos para usar un carácter diferente:

src/pages/test%25file.astro
src/pages/test-file.astro

Removido: módulo virtual astro:ssr-manifest (Integration API)

PR de implementación: feat: integrate vite environments (#14306)

En Astro 5.x, el módulo virtual deprecado astro:ssr-manifest aún podía usarse para acceder a valores de configuración.

Astro 6.0 elimina el módulo virtual astro:ssr-manifest por completo. Ya no es usado por integraciones ni internamente por Astro. El manifest ahora se pasa directamente a través de los hooks de integración y las APIs de adapter en lugar de a través de un módulo virtual. Para datos del manifest específicos del build, usa el hook de integración astro:build:ssr, que recibe el manifest como parámetro.

¿Qué debo hacer?

Si tu integración o código importa desde astro:ssr-manifest, usa astro:config/server en su lugar para acceder a los valores de configuración:

import { manifest } from 'astro:ssr-manifest';
import { srcDir, outDir, root } from 'astro:config/server';
// Use srcDir, outDir, root, etc. for configuration values

Aprende más sobre el módulo virtual astro:config.

Removido: RouteData.generate() (Adapter API)

PR de implementación: feat: integrate vite environments (#14306)

En Astro 5.x, las rutas podían ser generadas usando el método generate() en RouteData.

Astro 6.0 elimina RouteData.generate() porque la generación de rutas ahora es manejada internamente por Astro.

¿Qué debo hacer?

Elimina cualquier llamada a route.generate() en tu código. Este método ya no es necesario:

const generated = route.generate(params);

Aprende más sobre la Adapter API.

Removido: routes en el hook astro:build:done (Integration API)

PR de implementación: feat: cleanup integration api (#14446)

En Astro 5.0, acceder a routes en el hook astro:build:done fue deprecado.

Astro 6.0 elimina el array routes pasado a este hook por completo. En su lugar, se debe usar el hook astro:routes:resolved.

¿Qué debo hacer?

Elimina cualquier instancia de routes pasada a astro:build:done y reemplázala con el nuevo hook astro:routes:resolved. Accede a distURL en el mapa assets recién expuesto:

my-integration.mjs

const integration = () => {
    let routes
    return {
        name: 'my-integration',
        hooks: {
            'astro:routes:resolved': (params) => {
                routes = params.routes
            },
            'astro:build:done': ({
                routes
                assets
            }) => {
                for (const route of routes) {
                    const distURL = assets.get(route.pattern)
                    if (distURL) {
                        Object.assign(route, { distURL })
                    }
                }
                console.log(routes)
            }
        }
    }
}

Aprende más sobre el hook astro:routes:resolved de la Integration API para construir integraciones.

Removido: entryPoints en el hook astro:build:ssr (Integration API)

PR de implementación: feat: cleanup integration api (#14446)

En Astro 5.0, functionPerRoute fue deprecado. Eso significaba que entryPoints en el hook astro:build:ssr siempre estaba vacío.

Astro 6.0 elimina el map de entryPoints pasado a este hook por completo.

¿Qué debo hacer?

Elimina cualquier instancia de entryPoints pasada a astro:build:ssr:

my-integration.mjs

const integration = () => {
    return {
        name: 'my-integration',
        hooks: {
            'astro:build:ssr': (params) => {
                someLogic(params.entryPoints)
            },
        }
    }
}

Removido: signature antigua de app.render() (Adapter API)

PR de implementación: feat: clean deprecated APIs (#14462)

En Astro 4.0, la signature de app.render() que permitía pasar routeData y locals como argumentos opcionales fue deprecada en favor de un único argumento opcional renderOptions.

Astro 6.0 elimina esta signature por completo. Intentar pasar estos argumentos separados ahora causará un error en tu proyecto.

¿Qué debo hacer?

Revisa tus llamadas a app.render() y pasa routeData y locals como propiedades de un objeto en lugar de como múltiples argumentos independientes:

my-adapter/entrypoint.ts

app.render(request, routeData, locals)
app.render(request, { routeData, locals })

Aprende más sobre la Adapter API.

Removido: app.setManifestData() (Adapter API)

PR de implementación: chore(astro)!: remove app.setManifestData() (#14758)

En Astro 5.0, el método app.setManifestData() estaba disponible en App y NodeApp, pero ya no se usa ni es necesario.

Astro 6.0 elimina este método por completo.

¿Qué debo hacer?

Elimina cualquier llamada a app.setManifestData(). Si necesitas actualizar el manifest, crea una nueva instancia de App.

Aprende más sobre la Adapter API.

Removido: prop handleForms para el componente <ClientRouter />

PR de implementación: feat: clean deprecated APIs (#14462)

En Astro 4.0, la prop handleForms del componente <ClientRouter /> fue deprecada, ya que ya no era necesario optar por manejar eventos submit para elementos form. Esta funcionalidad se integró por defecto y la propiedad, si aún se incluía en tu proyecto, silenciosamente no tenía ningún impacto en el envío de formularios.

Astro 6.0 elimina esta prop por completo y ahora debe ser removida para evitar errores en tu proyecto.

¿Qué debo hacer?

Elimina la propiedad handleForms de tu componente <ClientRouter /> si existe. No ha proporcionado funcionalidad adicional, por lo que eliminarla no debería cambiar ningún comportamiento en tu proyecto:

src/pages/index.astro

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

Aprende más sobre transiciones con formularios.

Removido: prefetch() con opción with

PR de implementación: feat: clean deprecated APIs (#14462)

En Astro 4.8.4, la opción with de la función programática prefetch() fue deprecada en favor de un comportamiento por defecto más sensato que ya no requería especificar la prioridad de prefetching para cada página.

Astro 6.0 elimina esta opción por completo y ya no es posible configurar la prioridad de prefetching pasando la opción with. Intentar hacerlo ahora causará errores.

Por defecto, el prefetching de Astro ahora usa un enfoque automático que siempre intentará usar <link rel="prefetch> si es soportado, o recurrirá a fetch().

¿Qué debo hacer?

Revisa tus llamadas a prefetch() y elimina la opción with si aún existe:

prefetch('/about', { with: 'fetch' });
prefetch('/about');

Aprende más sobre prefetching.

Removido: rewrite() del contexto de Actions

PR de implementación: feat!: remove rewrite from action context (#14477)

En Astro 5.5.6, el método ActionAPIContext.rewrite() fue deprecado porque se deberían usar endpoints personalizados en lugar de rewrites.

Astro 6.0 elimina el método rewrite() de ActionAPIContext por completo y ya no puede ser usado.

¿Qué debo hacer?

Revisa tus handlers de Actions y elimina cualquier llamada a rewrite():

src/actions/index.ts

import { defineAction } from 'astro:actions';
import { z } from 'astro/zod';

export const server = {
  getGreeting: defineAction({
    input: z.object({
      // ...
    }),
    handler: async (input, context) => {
      context.rewrite('/')
      // ...
    }
  })
}

Aprende más sobre rewrites.

Removido: signature de función schema (Content Loader API)

PR de implementación: feat: loader.createSchema() (#14759)

En Astro 5.x, un content loader podía elegir definir un schema como una función en lugar de definir un objeto schema de Zod para validación. Esto es útil para generar dinámicamente el schema basándose en las opciones de configuración o introspeccionando una API.

Astro 6.0 elimina esta signature e introduce una nueva propiedad createSchema() como reemplazo para quienes aún quieran definir dinámicamente un schema en su content loader.

Proporcionar una función de schema de la manera antigua registrará un mensaje de advertencia de que el schema del loader está siendo ignorado, pero por lo demás el loader continuará funcionando como si no se hubiera proporcionado ningún schema. En una futura versión major, los loaders que proporcionen una función de schema lanzarán un error y no podrán usarse.

¿Qué debo hacer?

Si estás construyendo un content loader y usando una función para retornar dinámicamente una propiedad schema de colección, debes eliminar tu función existente y usar la nueva propiedad createSchema() para definir tu schema en su lugar.

Por ejemplo, puedes reproducir el comportamiento previo de Astro usando zod-to-ts directamente con createSchema() y cualquier lógica de función previa:

import type { Loader } from 'astro/loaders'
import { createTypeAlias, zodToTs } from 'zod-to-ts'
import { getSchemaFromApi } from './utils'

function myLoader() {
  return {
    name: 'my-loader',
    load: async (context) => {
      // ...
    },
    schema: async () => await getSchemaFromApi(),
    createSchema: async () => {
      const schema = await getSchemaFromApi()
      const identifier = 'Entry'
      const { node } = zodToTs(schema, identifier)
      const typeAlias = createTypeAlias(node, identifier)

      return {
        schema,
        types: `export ${typeAlias}`
      }
    }
  } satisfies Loader
}

Aprende más sobre createSchema() en la referencia de la Content Loader API.

Removido: session test driver

PR de implementación: feat(sessions): drivers (#15006)

En Astro 5.x, el session test driver interno se exportaba en los tipos de configuración de Astro, pero no estaba destinado a ser expuesto para uso público.

Astro 6.0 elimina el session test driver ya que ya no se usa internamente para probar context.session.

¿Qué debo hacer?

Es poco probable que estés usando esta API interna. Si lo haces, debes eliminar cualquier uso del session test driver:

astro.config.mjs

import { defineConfig } from 'astro/config'
import { createMockStorage } from './utils'

export default defineConfig({
  session: {
    driver: 'test',
    options: {
      mockStorage: createMockStorage()
    }
  }
})

Aprende más sobre la Session Driver API.

Removido: soporte para archivos de configuración CommonJS

PR de implementación: Drop cjs config support (#15192)

En Astro 5.x, el archivo de configuración de Astro podía usar cualquiera de las siguientes extensiones: .mjs, .js, .ts, .mts, .cjs y .cts.

Astro 6.0 elimina las extensiones .cjs y .cts.

¿Qué debo hacer?

Si tienes un archivo astro.config.cjs o astro.config.cts, actualízalo para usar una de las extensiones soportadas: .mjs, .js, .ts o .mts.

Aprende más sobre el archivo de configuración de Astro.

Flags experimentales

Los flags experimentales te permiten optar por funcionalidades mientras están en desarrollo temprano. Astro también puede usar flags experimentales para probar cambios importantes en el comportamiento por defecto. Los siguientes flags experimentales han sido removidos en Astro 6.0 y ahora son estables, o el nuevo comportamiento por defecto.

Elimina estos flags experimentales de tu configuración de Astro si los estabas usando previamente:

astro.config.mjs

import { defineConfig } from 'astro/config';

export default defineConfig({
  experimental: {
    csp: true,
    fonts: true,
    liveContentCollections: true,
    preserveScriptOrder: true,
    staticImportMetaEnv: true,
    headingIdCompat: true,
    failOnPrerenderConflict: true
  },
})

Funcionalidades experimentales ahora estables:

• csp (Consulta la referencia de configuración de security.csp para aprender más sobre Content Security Policy.)
• fonts (Consulta la guía de fonts actualizada para aprender más sobre cómo añadir fonts personalizadas a tu proyecto.)
• liveContentCollections (Consulta la documentación de content collections actualizada para aprender más sobre live collections.)
• failOnPrerenderConflict (Consulta la nueva opción de configuración prerenderConflictBehavior.)

Nuevo comportamiento por defecto o recomendado:

• preserveScriptOrder (Consulta a continuación los cambios importantes en el comportamiento por defecto de <script> y <style>.)
• staticImportMetaEnv (Consulta a continuación los cambios importantes en import.meta.env.)
• headingIdCompat (Consulta a continuación los cambios importantes en la generación de ID de encabezados Markdown.)

Lee sobre nuevas funcionalidades emocionantes y más en el post del blog de v6.0.

Valores por defecto cambiados

Algunos comportamientos por defecto han cambiado en Astro v6.0 y el código de tu proyecto podría necesitar actualización para tener en cuenta estos cambios.

En la mayoría de los casos, la única acción necesaria es revisar el despliegue de tu proyecto existente y asegurar que continúa funcionando como esperas, haciendo actualizaciones a tu código según sea necesario. En algunos casos, puede haber una configuración que te permita continuar usando el comportamiento por defecto anterior.

Cambiado: valor por defecto de i18n.routing.redirectToDefaultLocale

PR de implementación: feat(astro)!: update i18n.redirectToDefaultLocale default (#14406)

En Astro v5.0, el valor por defecto de i18n.routing.redirectToDefaultLocale era true. Cuando se combinaba con el valor por defecto de i18n.routing.prefixDefaultLocale de false, las redirecciones resultantes podían causar bucles infinitos.

En Astro v6.0, i18n.routing.redirectToDefaultLocale ahora tiene por defecto false. Adicionalmente, ahora solo puede usarse si i18n.routing.prefixDefaultLocale está establecido en true.

¿Qué debo hacer?

Revisa tu configuración de i18n de Astro ya que ahora podrías necesitar establecer explícitamente valores para redirectToDefaultLocale y prefixDefaultLocale para recrear el comportamiento previo de tu proyecto.

astro.config.mjs

import { defineConfig } from 'astro/config';

export default defineConfig({
  i18n: {
    routing: {
      prefixDefaultLocale: true,
      redirectToDefaultLocale: true
    }
  }
})

Si estás usando enrutamiento manual, también podrías necesitar actualizar tu configuración de middleware:

src/middleware.js

import { middleware } from "astro:i18n"; // Astro's own i18n routing config

export const onRequest = middleware({
  prefixDefaultLocale: false,
  prefixDefaultLocale: true,
  redirectToDefaultLocale: true,
})

Aprende más sobre enrutamiento de internacionalización.

Cambiado: las etiquetas <script> y <style> se renderizan en el orden en que se definen

PR de implementación: feat: stabilize experimental preserveScriptOrder option (#14480)

En Astro v5.5, el flag experimental.preserveScriptOrder fue introducido para renderizar múltiples etiquetas <style> y <script> en el mismo orden en que se declaraban en el código fuente. Astro 5.x invertía su orden en la salida HTML generada. Esto podía dar resultados inesperados, por ejemplo, estilos CSS siendo sobrescritos por etiquetas de estilo definidas anteriormente cuando tu sitio se compilaba.

Astro 6.0 elimina este flag experimental y hace este el nuevo comportamiento por defecto en Astro: los scripts y estilos ahora se renderizan en el orden definido en tu código.

¿Qué debo hacer?

Si estabas usando previamente esta funcionalidad experimental, debes eliminar este flag experimental de tu configuración ya que ya no existe.

Revisa tus etiquetas <script> y <style> para asegurar que se comportan como deseas. Podrías necesitar invertir su orden:

src/components/MyComponent.astro

<p>I am a component</p>
<style>
  body {
    background: red;
    background: yellow;
  }
</style>
<style>
  body {
    background: yellow;
    background: red;
  }
</style>
<script>
    console.log("hello")
    console.log("world")
</script>
<script>
    console.log("world!")
    console.log("hello!")
</script>

Lee más sobre el uso de etiquetas script y style.

Cambiado: cómo se emiten los estilos de imágenes responsive

PR de implementación: support responsive images (#15407)

En Astro 5.x, las imágenes se computaban en runtime y los estilos responsive de fit y pos se inyectaban en un atributo style. Esto no permitía compatibilidad con la Content Security Policy (CSP) de Astro por varias razones.

Astro 6 genera los estilos de imagen dentro de un módulo virtual en tiempo de build basándose en la configuración del proyecto, resultando en una clase hash y atributos data-* para aplicar estilos responsive a tus imágenes.

¿Qué debo hacer?

Inspecciona visualmente tus imágenes para asegurar que se están renderizando como se espera. Esto es un detalle de implementación que no debería afectar el uso esperado de imágenes responsive.

Sin embargo, si dependías de los estilos inline generados previamente para tus imágenes:

<img style="--fit: <value>; --pos: <value>" >

entonces necesitarás actualizar el código de tu proyecto para tener en cuenta los nuevos atributos data-* en su lugar:

<img class="__a_HaSh350" data-astro-fit="value" data-astro-pos="value" >

Cambios importantes

Los siguientes cambios se consideran cambios importantes en Astro v6.0. Los cambios importantes pueden o no proporcionar compatibilidad con versiones anteriores temporal. Si estabas usando estas funcionalidades, podrías tener que actualizar tu código como se recomienda en cada entrada.

Cambiado: los endpoints con una extensión de archivo no pueden ser accedidos con un trailing slash

PR de implementación: feat!: trailing slash never for endpoints with file extension (#14457)

En Astro v5.0, los endpoints personalizados cuya URL terminaba en una extensión de archivo (ej. /src/pages/sitemap.xml.ts ) podían ser accedidos con un trailing slash (/sitemap.xml/) o sin él (/sitemap.xml), independientemente del valor configurado para build.trailingSlash.

En Astro v6.0, estos endpoints solo pueden ser accedidos sin un trailing slash. Esto es cierto independientemente de tu configuración de build.trailingSlash.

¿Qué debo hacer?

Revisa tus enlaces a tus endpoints personalizados que incluyen una extensión de archivo en la URL y elimina cualquier trailing slash:

src/pages/index.astro

<a href="/sitemap.xml/">Sitemap</a>
<a href="/sitemap.xml">Sitemap</a>

Aprende más sobre endpoints personalizados.

Cambiado: los valores de import.meta.env siempre se inlinean

PR de implementación: feat: stabilize static import meta env (#14485)

En Astro 5.13, el flag experimental.staticImportMetaEnv fue introducido para actualizar el comportamiento al acceder directamente a import.meta.env para alinearse con el manejo de variables de entorno de Vite y asegurar que los valores de import.meta.env siempre se inlinean.

En Astro 5.x, las variables de entorno no públicas eran reemplazadas por una referencia a process.env. Adicionalmente, Astro también podía convertir el tipo de valor de tus variables de entorno usadas a través de import.meta.env, lo que podía prevenir el acceso a algunos valores como los strings "true" (que se convertía a un valor booleano), y "1" (que se convertía a un número).

Astro 6 elimina este flag experimental y hace este el nuevo comportamiento por defecto en Astro: los valores de import.meta.env siempre se inlinean y nunca se coercionan.

¿Qué debo hacer?

Si estabas usando previamente esta funcionalidad experimental, debes eliminar este flag experimental de tu configuración ya que ya no existe.

Si dependías de la coerción, podrías necesitar actualizar el código de tu proyecto para aplicarla manualmente:

src/components/MyComponent.astro

const enabled: boolean = import.meta.env.ENABLED;
const enabled: boolean = import.meta.env.ENABLED === "true";

Si dependías de la transformación a process.env, podrías necesitar actualizar el código de tu proyecto para aplicarla manualmente:

src/components/MyComponent.astro

const enabled: boolean = import.meta.env.DB_PASSWORD;
const enabled: boolean = process.env.DB_PASSWORD;

También podrías necesitar actualizar los tipos:

src/env.d.ts

interface ImportMetaEnv {
  readonly PUBLIC_POKEAPI: string;
  readonly DB_PASSWORD: string;
  readonly ENABLED: boolean;
  readonly ENABLED: string;
}

interface ImportMeta {
  readonly env: ImportMetaEnv;
}

namespace NodeJS {
  interface ProcessEnv {
    DB_PASSWORD: string;
  }
}

Si necesitas más control sobre las variables de entorno en Astro, te recomendamos usar astro:env.

Aprende más sobre las variables de entorno en Astro, incluyendo astro:env.

Cambiado: Recorte por defecto en el servicio de imágenes por defecto

PR de implementación: feat(assets): Always allow cropping and never upscale (#14629)

En Astro 5.0, el servicio de imágenes por defecto solo aplicaba recorte cuando se proporcionaba la opción fit.

Astro 6.0 aplica recorte por defecto sin requerir establecer la opción fit.

¿Qué debo hacer?

No se necesitan cambios en tus imágenes recortadas existentes ya que la propiedad fit sigue siendo válida. Sin embargo, si previamente estabas estableciendo fit en contain (su valor por defecto) para recortar tus imágenes, ahora puedes eliminar esta opción y aún lograr el mismo comportamiento de recorte especificando solo width y height:

src/components/MyImage.astro

---
import { Image } from 'astro:assets';
import myImage from '../assets/photo.jpg';
---
<Image src={myImage} width={400} height={300} fit="contain" />
<Image src={myImage} width={400} height={300} />

Cambiado: Nunca escalar imágenes en el servicio de imágenes por defecto

PR de implementación: feat(assets): Always allow cropping and never upscale (#14629)

En Astro 5.x, el servicio de imágenes por defecto escalaba las imágenes cuando las dimensiones solicitadas eran más grandes que la imagen original.

Astro 6.0 elimina este comportamiento: el servicio de imágenes por defecto nunca escala las imágenes.

¿Qué debo hacer?

Revisa tus imágenes y actualiza las dimensiones según sea necesario. Si necesitas escalar imágenes, puedes considerar escalar las imágenes manualmente o usar un servicio de imágenes personalizado que soporte escalado.

Cambiado: Rasterización de SVG

PR de implementación: add support for SVG rasterization (#15180)

En Astro v5.x, el servicio de imágenes Sharp por defecto de Astro no podía convertir archivos SVG a archivos raster (ej. PNG, WebP). Esto significaba que el componente <Image /> ignoraría cualquier valor establecido para format al optimizar y transformar archivos SVG.

Astro 6.0 ahora soporta rasterización de SVG. Esto está sujeto a muchas limitaciones, por ejemplo, los SVG con fonts embebidas podrían no convertirse correctamente. Sin embargo, cuando la propiedad format está establecida, el servicio de imágenes ahora intentará convertir las imágenes SVG.

¿Qué debo hacer?

Si dependías previamente del hecho de que el servicio de imágenes omitiría automáticamente la conversión de SVGs, ahora debes comprobar el formato de tus imágenes de antemano para evitar convertir SVGs a imágenes raster:

<Image src={imageThatMightBeAnSvg} format="avif" alt="example" />

<Image
  src={imageThatMightBeAnSvg}
  format={imageThatMightBeAnSvg.format === "svg" ? "svg" : "avif"}
  alt="example"
/>

Aprende más sobre la propiedad de imagen format.

Cambiado: getImage() lanza un error cuando se llama en el cliente

PR de implementación: feat: disallow getImage on the client (#15800)

En Astro 5.x, llamar a getImage() desde astro:assets en el cliente fallaba silenciosamente o producía resultados incorrectos.

Astro 6.0 lanza un error de runtime cuando getImage() se llama en el cliente.

¿Qué debo hacer?

Llama a getImage() en el servidor y pasa el src resultante al cliente en su lugar:

src/components/ClientImage.astro

---
import { getImage } from "astro:assets";
import myBackground from "../background.png";

const optimizedBackground = await getImage({ src: myBackground, format: "avif" });
---

<div id="background" data-src={optimizedBackground.src}></div>

<script>
  const src = document.getElementById("background").dataset.src;
  // use src client-side as needed
</script>

Consulta generación de imágenes con getImage() para un ejemplo completo.

Cambiado: Generación de ID de encabezados Markdown

PR de implementación: feat!: stabilize experimental.headingIdCompat (#14494)

En Astro 5.x, un paso de procesamiento por defecto adicional a Markdown eliminaba los guiones finales del final de los IDs para los encabezados de sección que terminaban en caracteres especiales. Esto proporcionaba un valor de id más limpio, pero podía llevar a incompatibilidades al renderizar tu Markdown en diferentes plataformas.

En Astro 5.5, el flag experimental.headingIdCompat fue introducido para permitirte hacer que los IDs generados por Astro para los encabezados Markdown sean compatibles con plataformas comunes como GitHub y npm, usando el paquete popular github-slugger.

Astro 6.0 elimina este flag experimental y hace este el nuevo comportamiento por defecto en Astro: los guiones finales del final de los IDs para encabezados que terminan en caracteres especiales ya no se eliminan.

¿Qué debo hacer?

Si tienes enlaces manuales a encabezados, podrías necesitar actualizar el valor del enlace ancla con un nuevo guión final. Por ejemplo, el siguiente encabezado Markdown:

## `<Picture />`

ahora generará el siguiente HTML con un guión final en el id del encabezado:

<h2 id="picture-"><code>&lt;Picture /&gt;</code></h2>

y ahora debe enlazarse como:

See [the Picture component](/en/guides/images/#picture-) for more details.

Si estabas usando previamente la funcionalidad experimental para forzar guiones finales, debes eliminar este flag experimental de tu configuración ya que ya no existe.

Si estabas usando previamente el plugin rehypeHeadingIds directamente para forzar compatibilidad, elimina la opción headingIdCompat ya que ya no existe:

astro.config.mjs

import { defineConfig } from 'astro/config';
import { rehypeHeadingIds } from '@astrojs/markdown-remark';
import { otherPluginThatReliesOnHeadingIDs } from 'some/plugin/source';

export default defineConfig({
  markdown: {
    rehypePlugins: [
      [rehypeHeadingIds, { headingIdCompat: true }],
      [rehypeHeadingIds],
      otherPluginThatReliesOnHeadingIDs,
    ],
  },
});

Si quieres mantener la generación de ID antigua por razones de compatibilidad con versiones anteriores, puedes crear un plugin rehype personalizado que genere los IDs de encabezados como Astro 5.x. Esto te permitirá continuar usando tus enlaces ancla existentes sin añadir guiones finales.

Crea un plugin rehype personalizado para eliminar guiones finales

1. Instala las dependencias requeridas:

   npm

   npm i github-slugger hast-util-heading-rank unist-util-visit hast-util-to-string

   pnpm

   pnpm add github-slugger hast-util-heading-rank unist-util-visit hast-util-to-string

   Yarn

   yarn add github-slugger hast-util-heading-rank unist-util-visit hast-util-to-string

2. Crea un plugin rehype personalizado que genere los IDs de encabezados como Astro v5:

   plugins/rehype-slug.mjs

   import GithubSlugger from 'github-slugger';
   import { headingRank } from 'hast-util-heading-rank';
   import { visit } from 'unist-util-visit';
   import { toString } from 'hast-util-to-string';
   
   const slugs = new GithubSlugger();
   
   export function rehypeSlug() {
     /**
      * @param {import('hast').Root} tree
      */
     return (tree) => {
       slugs.reset();
       visit(tree, 'element', (node) => {
         if (headingRank(node) && !node.properties.id) {
           let slug = slugs.slug(toString(node));
           // Strip trailing hyphens like in Astro v5 and below:
           if (slug.endsWith('-')) slug = slug.slice(0, -1);
           node.properties.id = slug;
         }
       });
     };
   }

3. Añade el plugin personalizado a tu configuración de Markdown en astro.config.mjs:

   astro.config.mjs

   import { defineConfig } from 'astro/config';
   import { rehypeSlug } from './plugins/rehype-slug';
   
   export default defineConfig({
     markdown: {
       rehypePlugins: [rehypeSlug],
     },
   });

Aprende más sobre IDs de encabezados.

Cambiado: getStaticPaths() no puede retornar params de tipo number

PR de implementación: fix!: disallow number in getStaticPaths params (#14586)

En Astro 5.x, getStaticPaths() podía retornar params de tipo number, que siempre serían convertidos a string por Astro. Sin embargo, eso podía ser confuso porque conflictuaba con los tipos de Astro.params.

Astro 6.0 elimina este comportamiento: getStaticPaths() ahora debe retornar valores de params de tipo string o undefined.

¿Qué debo hacer?

Revisa tus rutas dinámicas usando getStaticPaths() y convierte cualquier param de number a string:

src/pages/post/[id]/[label].astro

---
export function getStaticPaths() {
  return [
    {
      params: {
        id: 1,
        id: "1",
        label: "foo",
      }
    },
    {
      params: {
        id: 2,
        id: "2",
        label: "bar",
      }
    },
  ]
}
---

Aprende más sobre rutas SSG dinámicas con getStaticPaths().

Cambiado: Los componentes de Astro no pueden ser renderizados en entornos de cliente de Vitest (Container API)

PR de implementación: feat: remove Vitest workaround for client environment (#14895)

En Astro 5.x, renderizar un componente de Astro en el cliente estaba prohibido. Sin embargo, temporalmente permitimos este comportamiento en entornos de cliente de Vitest como jsdom o happy-dom usando la Container API experimental.

Astro 6.0 elimina la capacidad de renderizar componentes de Astro en entornos de cliente de Vitest: las pruebas que renderizan componentes de Astro ahora deben ejecutarse en un entorno de servidor como node.

¿Qué debo hacer?

Si usas Vitest para ejecutar pruebas que renderizan componentes de Astro en entornos de cliente como jsdom o happy-dom, actualiza tu configuración de Vitest para usar el entorno node para estas:

vitest.config.ts

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    environment: 'jsdom',
    environment: 'node',
  },
});

Aprende más sobre pruebas de componentes de Astro.

Cambiado: Ruta de configuración del nombre de archivo de salida de Rollup (Vite config)

PR de implementación: feat: integrate vite environments (#14306)

En Astro 5.x, las opciones personalizadas de nombre de archivo de salida de Rollup para assets de cliente podían configurarse en vite.build.rollupOptions.output.

Astro 6.0 limita la configuración de salida del build del cliente al entorno de cliente de Vite. Si personalizas entryFileNames, chunkFileNames, o assetFileNames para assets de cliente, usa vite.environments.client.build.rollupOptions.output.

¿Qué debo hacer?

Mueve tu configuración de vite.build.rollupOptions.output a vite.environments.client.build.rollupOptions.output:

astro.config.mjs

export default defineConfig({
  vite: {
    environments: {
      client: {
        build: {
          rollupOptions: {
            output: {
              entryFileNames: 'js/[name]-[hash].js',
            },
          },
        },
      },
    },
  },
});

Cambiado: Patrones de acceso a hooks de integración y HMR (Integration API)

PR de implementación: feat: integrate vite environments (#14306)

En Astro 5.x, Astro dependía de ciertos patrones para los hooks de integración y acceso a HMR que eran incompatibles con o podían mejorarse integrando la Environment API de Vite.

Astro 6.0 usa la nueva Environment API de Vite para la configuración de build y las interacciones del servidor de desarrollo. Esto principalmente habilita el modo dev en runtimes como workerd, pero significa que algunos hooks de integración y patrones de acceso a HMR han cambiado.

¿Qué debo hacer?

For integrations using astro:build:setup:

El hook ahora se llama una vez con todos los entornos configurados (ssr, client, prerender), en lugar de llamarse por separado para cada destino de build. Elimina el parámetro target y usa vite.environments para configurar entornos específicos:

my-integration.mjs

{
  hooks: {
    'astro:build:setup': ({ target, vite }) => {
      if (target === 'client') {
        vite.build.minify = false;
      }
    }
    'astro:build:setup': ({ vite }) => {
      vite.environments.client.build.minify = false;
    }
  }
}

Para código de dev toolbar e integración que accede a HMR:

Reemplaza server.hot.send() con server.environments.client.hot.send():

server.hot.send(event)
server.environments.client.hot.send(event)

Aprende más sobre la Vite Environment API y los hooks de integración de Astro.

Cambiado: Estructura de la interfaz SSRManifest (Adapter API)

PR de implementación: feat: integrate vite environments (#14306)

En Astro 5.x, las propiedades de ruta de la interfaz SSRManifest como srcDir, outDir, cacheDir, publicDir, buildClientDir, y buildServerDir eran strings de URL.

Astro 6.0 cambia la forma de estas propiedades de ruta a objetos URL en lugar de strings de URL. Con este cambio, varias propiedades nuevas ahora están disponibles en el manifest, y otras se han actualizado o removido.

¿Qué debo hacer?

Si estabas tratando estas propiedades de ruta como strings, ahora necesitarás manejar el objeto URL. Por ejemplo, ahora necesitarás acceder a la propiedad href del objeto URL:

// To retrieve the same format (e.g., "file:///path/to/src"), make the following change:
const srcPath = manifest.srcDir;
const srcPath = manifest.srcDir.href;

Si accedías a la propiedad hrefRoot, necesitarás eliminarla, ya que ya no está disponible en el manifest.

Actualiza cualquier uso de serverIslandMappings y sessionDriver. Estos ahora son métodos async:

const mappings = manifest.serverIslandMappings;
const driver = manifest.sessionDriver;
const mappings = await manifest.serverIslandMappings?.();
const driver = await manifest.sessionDriver?.();

Aprende más sobre la Adapter API.

Cambiado: los tipos de schema se infieren en lugar de generarse (Content Loader API)

PR de implementación: feat: loader.createSchema() (#14759)

En Astro 5.x, los tipos para content collections se generaban usando zod-to-ts cuando eran proporcionados por un content loader y no definidos por un schema proporcionado por el usuario.

Astro 6.0 elimina este comportamiento: los tipos ya no se generan usando zod-to-ts. En su lugar, los tipos se infieren.

¿Qué debo hacer?

Si estás proporcionando un schema en un content loader, debes usar el operador satisfies de TypeScript:

import type { Loader } from 'astro/loaders'

function myLoader(): Loader {
function myLoader() {
  return {
    name: 'my-loader',
    load: async (context) => {
      // ...
    },
    schema: z.object({/* ... */})
  }
  } satisfies Loader
}

Aprende más sobre definir tipos de schema de loader.

Problemas conocidos

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