Actualizando a la versión v2

Esta guía te ayudará a migrar de la versión Astro v1 a la Astro v2.

¿Necesitas actualizar un proyecto más antiguo a la v1? Ve nuestra guía de migración anterior (EN).

Actualiza la versión de tu proyecto Astro a la última versión usando el gestor de paquetes. Si estás utilizando alguna integración, también acutalizalas a la última versión.

Ventana de terminal
# Actualiza a la versión Astro v2.x
npm install astro@latest
# Ejemplo: actualiza las integraciones de React y Tailwind
npm install @astrojs/react@latest @astrojs/tailwind@latest

Astro v2.0 incluye algunos cambios importantes, así como la eliminación de algunas características previamente obsoletas. Si tu proyecto no funciona de forma esperada después de actualizarlo a la versión v2.0, consulta esta guía para obtener una descripción general de todos los cambios e instrucciones sobre cómo actualizar su base de código.

Ve el registro de cambios para las notas de la versión completa.

Node 14 está programado para llegar al final de su vida úitl en Abril de 2023.

Astro v2.0 elimina completamente el soporte para Node 14, para que todos los usuarios de Astro puedan aprovechar las caraacterísticas más modernas de Node.

Verifica que tanto tu entorno de desarrollo como tu entorno de producción estén usando Node 16.12.0 o superior.

  1. Verifica la versión local de Node usando:

    Ventana de terminal
    node -v

    Si tu entorno de desarrollo necesita actualizarse, instala Node.

  2. Verifica la propia documentación del entorno de producción para verificar que ellos soportan Node 16.

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

Astro v2.0 ahora incluye la API de Colecciones para organizar tus archivos Markdown y MDX en colecciones de contenido. Esta API reserva src/content/ como una carpeta especial.

Renombra la carpeta existente src/content/ para evitar conflictos. Esta carpeta, si es que existe, ahora solo se puede usar para colecciones de contenido.

En la versión v1.x, Astro se aseguraba que el URL que se pasaba a site en astro.config.mjs siempre tuviera una barra lateral cuando fuese accesado usando Astro.site.

Astro v2.0 ya no modifica el valor de site. Astro.site usará el valor exacto definido, y se debe especificar una barra lateral si se desea.

En astro.config.mjs, agrega una barra lateral al URL definido en site.

astro.config.mjs
import { defineConfig } from 'astro/config';
export default defineConfig({
site: 'https://ejemplo.com',
site: 'https://ejemplo.com/',
});

Cambió: _astro/ carpeta para activos de compilación

Sección titulada Cambió: _astro/ carpeta para activos de compilación

En la versión v1.x, los activos se compilaban en varias ubicaciones, incluyendo assets/, chunks/, y en la raíz de la carpeta de compilación.

Astro v2.0 mueve y une la ubicación de todos los activos de compilación en una nueva carpeta _astro/.

  • Directoriodist/
    • Directorio_astro
      • client.9218e799.js
      • index.df3f880e0.css

Puedes controlar esta ubicación con la nueva opción de configuración build.assets.

Actualiza la configuración de tu plataforma de despliegue si depende de la ubicación de estos activos.

Cambió: Configuración del plugin Markdown

Sección titulada Cambió: Configuración del plugin Markdown

En la versión v1.x, Astro usaba markdown.extendDefaultPlugins para volver a habilitar los plugins predeterminados de Astro al agregar tus propios plugins de Markdown.

Astro v2.0 elimina completamente esta opción de configuración porque ahora su comportamiento es el predeterminado.

Aplicando plugins de remark y rehype en tu configuración de Markdown ya no deshabilita los plugins predeterminados de Astro. GitHub-Flavored Markdown y Smartypants ahora se aplican independientemente de si se configuran remarkPlugins o rehypePlugins personalizados.

Elimina extendDefaultPlugins de tu configuración. Esto es ahora el comportamiento predeterminado de Astro en la v2.0 y puedes eliminar esta línea sin ningún reemplazo.

astro.config.mjs
import { defineConfig } from 'astro/config';
export default defineConfig({
markdown: {
extendDefaultPlugins,
}
});

En la versión v1.x, podías elegir deshabilitar ambos plugins predeterminados de Markdown de Astro (GitHub-Flavored Markdown y SmartyPants) configurando markdown.extendDefaultPlugins: false.

Astro v2.0 remplaza markdown.extendDefaultPlugins: false con opciones booleanas separadas para controlar individualmente cada uno de los plugins predeterminados de Markdown de Astro. Estos están habilitados por defecto y se pueden configurar como false de forma independiente.

Elimina extendDefaultPlugins: false y agrega las opciones para deshabilitar cada plugin individualmente en su lugar.

  • markdown.gfm: false deshabilita GitHub-Flavored Markdown
  • markdown.smartypants: false deshabilita SmartyPants
astro.config.mjs
import { defineConfig } from 'astro/config';
export default defineConfig({
markdown: {
extendDefaultPlugins: false,
smartypants: false,
gfm: false,
}
});

Cambió: Configuración del plugin MDX

Sección titulada Cambió: Configuración del plugin MDX

Reemplazado: extendPlugins reemplazado por extendMarkdownConfig

Sección titulada Reemplazado: extendPlugins reemplazado por extendMarkdownConfig

En la versión v1.x, la integración de MDX extendPlugins administraba cómo tus archivos MDX debían heredar tu configuración de Markdown: toda tu configuración de Markdown (markdown) o solo los plugins predeterminados de Astro (default).

Astro v2.0 reemplaza el comportamiento controlado por mdx.extendPlugins con tres nuevas opciones configurables de forma independiente que están habilitadas por defecto:

  • mdx.extendMarkdownConfig para heredar todas o ninguna de las opciones de configuración de Markdown
  • mdx.gfm para habilitar o deshabilitar GitHub-Flavored Markdown en MDX
  • mdx.smartypants para habilitar o deshabilitar SmartyPants en MDX

Borra extendPlugins: 'markdown' de tu configuración. Este es ahora el comportamiento predeterminado.

astro.config.mjs
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
export default defineConfig({
integrations: [
mdx({
extendPlugins: 'markdown',
}),
],
});

Reemplaza extendPlugins: 'defaults' con extendMarkdownConfig: false y agrega las opciones separadas para GitHub-Flavored Markdown y SmartyPants para habilitar estos plugins predeterminados individualmente en MDX.

astro.config.mjs
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
export default defineConfig({
integrations: [
mdx({
extendPlugins: 'defaults',
extendMarkdownConfig: false,
smartypants: true,
gfm: true,
}),
],
});

Agregado: Más opciones de configuración de MDX para que coincida con Markdown

Sección titulada Agregado: Más opciones de configuración de MDX para que coincida con Markdown

Astro v2.0 ahora te permite configurar individualmente cada opción de configuración de Markdown disponible (excepto drafts) por separado en tu configuración de integración MDX.

astro.config.mjs
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
export default defineConfig({
markdown: {
remarkPlugins: [remarkPlugin1],
gfm: true,
},
integrations: [
mdx({
remarkPlugins: [remarkPlugin2],
gfm: false,
})
]
});

Revisa tu configuración de Markdown y MDX y compare tu configuración existente con las nuevas opciones disponibles.

Cambió: Plugin de acceso al frontmatter

Sección titulada Cambió: Plugin de acceso al frontmatter

En la versión v1.x, los plugins de remark y rehype no tenían acceso al frontmatter del usuario. Astro fusionó el frontmatter del plugin con el frontmatter de tu archivo, sin pasar el frontmatter del archivo a tus plugins.

Astro v2.0 da acceso a los plugins de remark y rehype al frontmatter del usuario a través de la inyección de frontmatter. Esto permite a los autores de plugins modificar el frontmatter existente del usuario o calcular nuevas propiedades en función de otras propiedades.

Verifica cualquier plugin de remark y rehype que hayas escrito para ver si su comportamiento ha cambiado. Ten en cuenta que data.astro.frontmatter ahora es el frontmatter completo del documento Markdown o MDX, en lugar de un objeto vacío.

En la versión v1.x, el paquete RSS de Astro te permitía usar items: import.meta.glob(...) para generar una lista de elementos de feed RSS. Ahora su uso es obsoleto y eventualmente se eliminará.

Astro v2.0 introduce un wrapper pagesGlobToRssItems() para la propiedad items.

Importa, luego envuelve tu función existente que contiene import.meta.glob() con el helper pagesGlobToRssItems().

src/pages/rss.xml.js
import rss, {
pagesGlobToRssItems
} from '@astrojs/rss';
export async function get(context) {
return rss({
items: await pagesGlobToRssItems(
import.meta.glob('./blog/*.{md,mdx}'),
),
});
}

Astro 2.0 requiere un archivo svelte.config.js en tu proyecto si estás usando la integración @astrojs/svelte. Esto es necesario para proporcionar autocompletado de IDE.

Agrega un archivo svelte.config.js en la raíz de tu proyecto:

svelte.config.js
import { vitePreprocess } from '@astrojs/svelte';
export default {
preprocess: vitePreprocess(),
};

Para nuevos usuarios, este archivo se agregará automáticamente al ejecutar astro add svelte.

Eliminado: legacy.astroFlavoredMarkdown

Sección titulada Eliminado: legacy.astroFlavoredMarkdown

En la versión v1.0, Astro migró al antiguo Astro-Flavored Markdown (también conocido como Componentes en Markdown) a una característica obsoleta.

Astro v2.0 elimina por completo la opción legacy.astroFlavoredMarkdown. La importación y el uso de componentes en archivos .md ya no funcionarán.

Elimina esta flag obsoleta. Ya que no está disponible en Astro.

astro.config.mjs
export default defineConfig({
legacy: {
astroFlavoredMarkdown: true,
},
})

Si tu usabas esta característica en v1.x, recomendamos usar la integración MDX que te permite combinar componentes y expresiones JSX con la sintaxis de Markdown.

En la version v0.24, Astro marcó como obsoleto Astro.resolve() por obtener URLs resueltas a recursos que podrías querer referenciar en el navegador.

Astro v2.0 elimina completamente esta opción. Astro.resolve() causará un error en tu código.

Resuelve las rutas de los recursos usando import en su lugar. Por ejemplo:

src/pages/index.astro
---
import 'style.css';
import imageUrl from './image.png';
---
<img src={imageUrl} />

En la versión v0.26, Astro marcó como obsoleto Astro.fetchContent() por obtener datos de tus archivos Markdown locales.

Astro v2.0 elimina completamente esta opción. Astro.fetchContent() causará un error en tu código.

Usa Astro.glob() para obtener archivos Markdown o usa la característica Colección de Contenido.

src/pages/index.astro
---
const allPosts = await Astro.glob('./posts/*.md');
---

En la versión v1.0, Astro marcó como obsoleto Astro.canonicalURL por construir una URL canónica.

Astro v2.0 elimina esta opción completamente. Astro.canonicalURL causará un error en tu código.

Usa Astro.url para construir una URL canónica.

src/pages/index.astro
---
const canonicalURL = new URL(Astro.url.pathname, Astro.site);
---

Astro v2.0 actualiza de Vite 3 a Vite 4, lanzado en Diciembre de 2022.

No deberías tener que hacer cambios en tu código. ¡Hemos manejado la mayoría de la actualización para ti dentro de Astro; sin embargo, algunos comportamientos sutiles de Vite aún pueden cambiar entre versiones.

Refierete a la guía oficial de migración de Vite si tienes problemas.

Astro v2.0 Opciones Experimentales Eliminados

Sección titulada Astro v2.0 Opciones Experimentales Eliminados

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

astro.config.mjs
import { defineConfig } from 'astro/config';
export default defineConfig({
experimental: {
contentCollections: true,
prerender: true,
errorOverlay: true,
},
})

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

No hay problemas identificados actualmente.