Astro 5.5

Por
Matt Kane

¡Astro 5.5 se sumerge en profundidad con mejor soporte para herramientas de diagramación, compatibilidad mejorada de Markdown, y sessions type-safe!

🧜‍♀️ Sumérgete en un mar de nuevas características con estas mejoras en Astro:

Para actualizar un proyecto existente, usa la herramienta CLI automatizada @astrojs/upgrade. Alternativamente, actualiza manualmente ejecutando el comando de actualización para tu gestor de paquetes:

# Recommended:
npx @astrojs/upgrade


# Manual:
npm install astro@latest
pnpm upgrade astro --latest
yarn upgrade astro --latest

Mejor soporte para herramientas de diagramación en Markdown

Herramientas como Mermaid y D2 te permiten definir gráficos y diagramas en bloques de código en Markdown, que luego se renderizan dentro del contenido. Hasta ahora, usar estos en Astro podía ser complicado, porque el syntax highlighting por defecto de Astro interfería con cómo se renderizaban los bloques de código.

Astro 5.5 introduce una nueva opción excludeLangs en tu configuración de Markdown que hace posible saltarse el syntax highlighting para bloques de código de lenguajes específicos. Esto desbloquea la capacidad de usar herramientas como estas sin deshabilitar el syntax highlighting para otros bloques.

Aquí hay un ejemplo de cómo configurar Astro para deshabilitar el highlighting para el lenguaje mermaid después de instalar el plugin rehype-mermaid:

astro.config.mjs
import { defineConfig } from 'astro/config';
import rehypeMermaid from 'rehype-mermaid';


export default defineConfig({
  markdown: {
    syntaxHighlight: {
      type: 'shiki',
      excludeLangs: ['mermaid', 'math'],
    },
    rehypePlugins: [rehypeMermaid],
  },
});

Luego, puedes crear diagramas directamente en tu contenido Markdown:

```mermaid
graph TD
    A[Start] --> B{Is it working?}
    B -->|Yes| C[Great!]
    B -->|No| D[Debug]
    D --> B
```

Esto luego se renderizará como un diagrama en tu página.

Un enorme agradecimiento a Chris Chua por esta contribución.

Sessions experimentales type-safe

Astro 5.5 añade soporte para tipado adecuado de TypeScript para tus datos de session, permitiéndote desterrar los errores de any. El soporte experimental para session storage se añadió en Astro 5.1, pero anteriormente todos los datos de session eran untyped. Ahora puedes definir los tipos de tus datos de session extendiendo la interfaz global App.SessionData en el archivo src/env.d.ts de tu proyecto:

src/env.d.ts
declare namespace App {
  interface SessionData {
    user: {
      id: string;
      email: string;
    };
    lastLogin: Date;
  }
}

Esto es opcional, y cualquier key no definida en esta interfaz se tratará como any. Sin embargo, definir los tipos proporcionará type checking y autocomplete precisos al trabajar con datos de session en tu sitio:

---
const user = await Astro.session.get('user');
// `user` is properly typed as `{ id: string; email: string; } | undefined`


const something = await Astro.session.get('something');
// `something` is typed as `any` since it's not defined in the interface


// TypeScript will catch this error:
Astro.session.set('user', 1); // Error: Type 'number' is not assignable to type '{ id: string; email: string; }'
---

Esta mejora hace que trabajar con sessions en Astro sea más fiable y ayuda a detectar errores potenciales en tiempo de desarrollo en lugar de en tiempo de ejecución.

Para más información, consulta la documentación de sessions experimentales.

Compatibilidad mejorada de heading ID

Astro 5.5 introduce un nuevo flag experimental.headingIdCompat que genera heading IDs consistentes con otros procesadores comunes de Markdown como los usados por GitHub y npm.

Por defecto, Astro elimina los guiones finales del final de los IDs que genera para headings que contienen caracteres especiales. Este comportamiento difiere de otros procesadores comunes de Markdown, lo que puede causar inconsistencias al enlazar a headings a través de diferentes plataformas.

Con el nuevo flag de configuración, ahora puedes asegurar que tus heading IDs sigan la misma convención que otras plataformas:

astro.config.mjs
import { defineConfig } from 'astro/config';


export default defineConfig({
  experimental: {
    headingIdCompat: true,
  },
});

Esto es particularmente útil para sitios que podrían tener anchor links compartidos entre GitHub, documentación de npm, y tu sitio web de Astro.

Experimental: preservar el orden de los tags style y script

Los flags experimentales no son solo para características nuevas y geniales. A veces, las cosas simplemente tienen que cambiar. También usamos flags experimentales para introducirte cuidadosamente breaking changes que eventualmente se convertirán en el nuevo comportamiento por defecto. experimental.preserveScriptOrder es uno de ellos.

Al renderizar múltiples tags <style> y <script> en la misma página, Astro actualmente invierte su orden en la salida HTML generada. Esto puede dar resultados inesperados, por ejemplo estilos CSS que aplican en modo desarrollo siendo sobrescritos por tags style anteriores una vez que tu sitio está compilado.

Puedes habilitarlo en tu configuración así:

astro.config.mjs
import { defineConfig } from 'astro/config';


export default defineConfig({
  experimental: {
    preserveScriptOrder: true,
  },
});

Con el nuevo flag preserveScriptOrder establecido a true, Astro generará tus estilos y scripts en el orden en que están definidos. Si anteriormente estabas compensando el comportamiento de Astro escribiéndolos desordenados, necesitarás actualizar tu código.

Creemos que este cambio tiene sentido a largo plazo para todos, así que te animamos a probarlo ahora para asegurar que funciona antes de que se convierta en el comportamiento por defecto.

¡Gracias a JaneSmith por identificar primero este issue, y a Reuben Tier por contribuir el fix del compiler!

Correcciones de bugs

Como siempre, hemos estado trabajando duro en corregir problemas desde el lanzamiento 5.4. Consulta el changelog para todos los detalles.

Gracias

Gracias a todos los que contribuyeron a este lanzamiento, incluyendo Chris Swithinbank, Emanuele Stoppa, Reuben Tier, Luiz Ferraz, Sarah Rainsberger, HiDeoo, HappyDev, Yan Thomas, Bjorn Lu, Chris Chua, y muchos más.

¡Esperamos ver qué construís con Astro 5.5! Si tienes preguntas, comentarios, o solo quieres decir hola, pásate por el Astro Discord.