Actualizar a Astro v2

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

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

Actualizar Astro

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

npm

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

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

pnpm

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

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

Yarn

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

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

Cambios importantes de Astro v2.0

Astro v2.0 incluye algunos cambios importantes, así como la remoción de algunas funcionalidades previamente deprecadas. Si tu proyecto no funciona como se espera después de actualizar a v2.0, consulta esta guía para una descripción general de todos los cambios importantes e instrucciones sobre cómo actualizar tu código base.

Consulta el changelog para las notas de release completas.

Removido: Soporte para Node 14

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

Astro v2.0 elimina el soporte para Node 14 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 16.12.0 o posterior.

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

   node -v

   Si tu entorno de desarrollo local necesita actualización, instala Node.

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

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

Reservado: src/content/

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

¿Qué debo hacer?

Renombra una carpeta src/content/ existente para evitar conflictos. Esta carpeta, si existe, ahora solo puede usarse para content collections.

Cambiado: Barra diagonal final de Astro.site

En v1.x, Astro aseguraba que la URL que estableciste como site en astro.config.mjs siempre tuviera una barra diagonal final cuando se accedía usando Astro.site.

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

¿Qué debo hacer?

En astro.config.mjs, añade una barra diagonal final a la URL establecida en site.

astro.config.mjs

import { defineConfig } from 'astro/config';

export default defineConfig({
  site: 'https://example.com',
  site: 'https://example.com/',
});

Cambiado: Carpeta _astro/ para assets de build

En v1.x, los assets se construían en varias ubicaciones, incluyendo assets/, chunks/, y la raíz de la salida del build.

Astro v2.0 mueve y unifica la ubicación de todos los assets de salida del build a 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.

¿Qué debo hacer?

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

Cambiado: Configuración de plugins de Markdown

Removido: extendDefaultPlugins

En v1.x, Astro usaba markdown.extendDefaultPlugins para re-habilitar los plugins por defecto de Astro al añadir tus propios plugins de Markdown.

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

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

¿Qué debo hacer?

Elimina extendDefaultPlugins en tu configuración. Este es ahora el comportamiento por defecto de Astro en v2.0, y puedes eliminar esta línea sin reemplazo.

astro.config.mjs

import { defineConfig } from 'astro/config';

export default defineConfig({
  markdown: {
    extendDefaultPlugins,
  }
});

Añadido: gfm y smartypants

En v1.x, podías elegir deshabilitar ambos plugins por defecto de Markdown de Astro (GitHub-Flavored Markdown y SmartyPants) estableciendo markdown.extendDefaultPlugins: false.

Astro v2.0 reemplaza markdown.extendDefaultPlugins: false con opciones Boolean separadas para controlar individualmente cada uno de los plugins por defecto de Markdown integrados de Astro. Estos están habilitados por defecto y pueden establecerse en false independientemente.

¿Qué debo hacer?

Elimina extendDefaultPlugins: false y añade los flags 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,
  }
});

Cambiado: Configuración de plugins de MDX

Reemplazado: extendPlugins cambiado a extendMarkdownConfig

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

Astro v2.0 reemplaza el comportamiento controlado por mdx.extendPlugins con tres nuevas opciones configurables independientemente que están en true por defecto:

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

¿Qué debo hacer?

Elimina extendPlugins: 'markdown' en tu configuración. Este es ahora el comportamiento por defecto.

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 añade las opciones separadas para GitHub-Flavored Markdown y SmartyPants para habilitar estos plugins por defecto 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,
    }),
  ],
});

Añadido: Más opciones de configuración MDX para coincidir con Markdown

Astro v2.0 ahora te permite establecer individualmente cada opción de configuración de Markdown disponible (excepto drafts) separadamente en la configuración de tu 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,
    })
  ]
});

¿Qué debo hacer?

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

Cambiado: Acceso de plugins al frontmatter

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

Astro v2.0 da a los plugins de remark y rehype acceso al frontmatter del usuario vía inyección de frontmatter. Esto permite a los autores de plugins modificar el frontmatter existente de un usuario, o calcular nuevas propiedades basadas en otras propiedades.

¿Qué debo hacer?

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

Cambiado: Configuración RSS

En v1.x, el paquete RSS de Astro permitía usar items: import.meta.glob(...) para generar una lista de items de feed RSS. Este uso ahora está deprecado y eventualmente será removido.

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

¿Qué debo hacer?

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

Cambiado: Soporte IDE de Svelte

Astro v2.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 en el IDE.

¿Qué debo hacer?

Añade un archivo svelte.config.js a la raíz de tu proyecto:

svelte.config.js

import { vitePreprocess } from '@astrojs/svelte';

export default {
  preprocess: vitePreprocess(),
};

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

Removido: legacy.astroFlavoredMarkdown

En v1.0, Astro movió el viejo Astro-Flavored Markdown (también conocido como Componentes en Markdown) a una funcionalidad legacy.

Astro v2.0 elimina la opción legacy.astroFlavoredMarkdown por completo. Importar y usar componentes en archivos .md ya no funcionará.

¿Qué debo hacer?

Elimina este flag legacy. Ya no está disponible en Astro.

astro.config.mjs

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

Si estabas usando esta funcionalidad en v1.x, recomendamos usar la integración MDX que te permite combinar componentes y expresiones JSX con sintaxis Markdown.

Removido: Astro.resolve()

En v0.24, Astro deprecó Astro.resolve() para obtener URLs resueltas a assets que podrías querer referenciar en el navegador.

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

¿Qué debo hacer?

Resuelve rutas de assets usando import en su lugar. Por ejemplo:

src/pages/index.astro

---
import 'style.css';
import imageUrl from './image.png';
---

<img src={imageUrl} />

Removido: Astro.fetchContent()

En v0.26, Astro deprecó Astro.fetchContent() para obtener datos de tus archivos Markdown locales.

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

¿Qué debo hacer?

Usa Astro.glob() para obtener archivos Markdown, o conviértete a la funcionalidad de Content Collections.

src/pages/index.astro

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

Removido: Astro.canonicalURL

En v1.0, Astro deprecó Astro.canonicalURL para construir una URL canónica.

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

¿Qué debo hacer?

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

src/pages/index.astro

---
const canonicalURL = new URL(Astro.url.pathname, Astro.site);
---

Actualizado: Vite 4

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

¿Qué debo hacer?

¡No debería ser necesario hacer cambios en tu código! Hemos manejado la mayor parte de la actualización por ti dentro de Astro; sin embargo, algunos comportamientos sutiles de Vite pueden cambiar entre versiones.

Consulta la Guía de Migración de Vite oficial si tienes problemas.

Flags experimentales de Astro v2.0 removidos

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

astro.config.mjs

import { defineConfig } from 'astro/config';

export default defineConfig({
  experimental: {
    contentCollections: true,
    prerender: true,
    errorOverlay: true,
  },
})

Estas funcionalidades ahora están disponibles por defecto:

• Content collections como una forma de gestionar tus archivos Markdown y MDX con seguridad de tipos.
• Pre-renderizar páginas individuales a HTML estático cuando se usa SSR para mejorar velocidad y cacheabilidad.
• Un overlay de mensajes de error rediseñado.

Problemas conocidos

Actualmente no hay problemas conocidos.