Astro 5.6

Por
Matt Kane
Emanuele Stoppa

Astro 5.6 trae soporte first-class de astro:env y sessions experimentales a Cloudflare, y da más control sobre el prefetching.

☁️ Vuela a través de las nubes con estas nuevas características 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

astro:env global en Cloudflare

Desde Astro 5, has podido acceder a variables de entorno type-safe usando astro:env. Sin embargo, las variables de entorno en Cloudflare solo eran accesibles dentro de una petición — limitando cuándo y dónde podías usarlas. Por ejemplo, si querías usar una instancia compartida de un API client, no podías usar variables de entorno si la instanciabas fuera de una petición. Esto podía ser confuso y era diferente de nuestros otros adaptadores.

Astro 5.6 elimina esta restricción, lo que significa que ahora puedes acceder a tus variables de entorno globalmente en todo tu código del servidor y pone al adaptador de Cloudflare en línea con los otros adaptadores oficiales. Esto es posible gracias a mejoras en Cloudflare Workers que ahora están implementadas en Astro.

import { defineMiddleware } from 'astro:middleware';
import { API_URL } from 'astro:env/server';
import { createClient } from './client.js';


// Astro 5.5: undefined
// Astro 5.6: string
const client = createClient(API_URL);


export const onRequest = defineMiddleware((ctx, next) => {
  ctx.locals.client = client;
  return next();
});

Esta mejora crea una experiencia de desarrollador más consistente en todos los entornos de servidor de Astro, y significa que no necesitas preocuparte por averiguar qué cuenta como request scope o global scope.

Sessions experimentales en Cloudflare

La Astro sessions API es una característica experimental que te permite almacenar fácilmente datos de usuario entre peticiones. Usa backends plugables para almacenamiento, que se configuran automáticamente al usar los adaptadores de Node o Netlify.

Con Astro 5.6, hemos llevado esa integración simplificada a Cloudflare también. Astro ahora configura automáticamente el almacenamiento de Cloudflare KV cuando estás usando sessions con el adaptador de Cloudflare. Esto significa que tus datos de session pueden almacenarse y accederse de forma fiable a través de la red global de Cloudflare con configuración mínima.

Empezar son tres pasos:

  1. Crea un KV namespace usando el CLI de Wrangler:

    npx wrangler kv namespace create "SESSION"

  2. Declara el KV namespace en tu configuración de Wrangler:

    wrangler.json
    {
      "kv_namespaces": [
        {
          "binding": "SESSION",
          "id": "<SESSION_ID>"
        }
      ]
    }

  3. Habilita las sessions experimentales en tu configuración de Astro:

    astro.config.mjs
    export default defineConfig({
      adapter: cloudflare(),
      experimental: {
        sessions: true,
      },
    });

Luego puedes usar sessions en tu código del servidor:

---
export const prerender = false;
const cart = await Astro.session.get('cart');
---


<a href="/checkout">🛒 {cart?.length ?? 0} items</a>

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

Nueva opción de Prefetch Eagerness

Encuentra el equilibrio perfecto entre velocidad y uso de recursos con los nuevos controles de prefetch eagerness de Astro. Con el flag experimental clientPrerender habilitado, puedes usar la opción eagerness en prefetch() para sugerirle al browser con qué eagerness debería hacer prefetch/prerender de los destinos de los enlaces.

Esta nueva opción, que se alinea con la Speculation Rules API del browser, te da control fino sobre con qué agresividad el browser debería hacer prefetch o prerender de tus enlaces:

---
---
<script>
// Control prefetching eagerness
import { prefetch } from 'astro:prefetch';


// Let's be strategic about this resource-intensive page
prefetch('/data-heavy-dashboard', { eagerness: 'conservative' });


// This page is critical to the user journey, load it ASAP!
prefetch('/product-details'); // defaults to `{ eagerness: 'immediate' }`


// For most pages, a balanced approach works best
prefetch('/about', { eagerness: 'moderate' });
</script>

Puedes elegir entre tres niveles de eagerness:

  • 'immediate': Prefetch inmediatamente, si los límites de recursos lo permiten
  • 'eager': Es probable que el enlace se necesite, así que obtenerlo lo antes posible
  • 'moderate': Dejar que el browser decida cuándo hacer prefetch
  • 'conservative': Solo hacer prefetch cuando sea muy probable que se necesite

Esta característica es particularmente valiosa cuando se trata de grandes números de enlaces donde de otro modo podrías encontrarte con límites del browser para proteger contra exceso de especulación.

¡Gracias al miembro de la comunidad Marocco2 por contribuir esta característica!

Opción de Fetch Personalizado para Páginas de Error Prerenderizadas

Cuando una página renderizada bajo demanda necesita mostrar un error, tu adaptador puede necesitar obtener una página de error prerenderizada desde un lugar distinto a tu servidor. Actualmente, esto se hace realizando una petición usando la implementación fetch por defecto, que puede no ser adecuada para todos los casos de uso. Por ejemplo, la página puede servirse desde una ubicación que no puede llamarse recursivamente, o la página puede estar almacenada en otro lugar.

Astro 5.6 añade una nueva opción opcional prerenderedErrorPageFetch en la Adapter API para permitir a los adaptadores proporcionar implementaciones personalizadas para obtener páginas de error prerenderizadas.

El siguiente ejemplo proporciona un fetch personalizado para 500.html y 404.html, leyéndolos desde disco en lugar de realizar una llamada HTTP:

return app.render(request, {
  prerenderedErrorPageFetch: async (url: string): Promise<Response> => {
    if (url.includes("/500")) {
        const content = await fs.promises.readFile("500.html", "utf-8");
        return new Response(content, {
          status: 500,
          headers: { "Content-Type": "text/html" },
        });
    }
    const content = await fs.promises.readFile("404.html", "utf-8");
      return new Response(content, {
        status: 404,
        headers: { "Content-Type": "text/html" },
      });
});

Si no se proporciona ningún valor, Astro usará fetch, y hará una petición a /500 o /404 según corresponda. Este es el mismo comportamiento que en versiones anteriores de Astro.

Lee más sobre esta característica en la referencia de la Adapter API.

¡Gracias a Yury Michurin por contribuir esta característica!

Nuevo método load() para sessions experimentales

Al usar la Sessions API experimental, normalmente no necesitas preocuparte por gestionar el session ID y las cookies: Astro automáticamente lee las cookies del usuario y carga la session correcta cuando se necesita. Sin embargo, a veces necesitas más control sobre qué session cargar.

El nuevo método load() te permite cargar manualmente una session por ID. Esto es útil si estás manejando el session ID tú mismo, o si quieres rastrear una session sin usar cookies. Por ejemplo, podrías querer restaurar una session de un usuario con sesión iniciada en otro dispositivo, o trabajar con un API endpoint que no usa cookies.

src/pages/api/cart.ts
import type { APIRoute } from 'astro';


export const GET: APIRoute = async ({ session, request }) => {
  // Load the session from a header instead of cookies
  const sessionId = request.headers.get('x-session-id');
  await session.load(sessionId);
  const cart = await session.get('cart');
  return Response.json({ cart });
};

Si no existe una session con ese ID, se creará una nueva. Esto te permite generar un session ID en el cliente si es necesario.

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

Validación de Configuración Mejorada

Astro ahora valida tu configuración después de que cada integración se ejecuta, haciendo más fácil detectar problemas temprano y localizar la fuente de cualquier problema. Esto es particularmente útil cuando se usan múltiples integraciones, ya que ayuda a asegurar que todas sean compatibles entre sí y con tu proyecto de Astro.

Breaking changes en la API experimental de SVG

El RFC experimental de SVG ha estado bajo fuerte discusión, y por eso ¡agradecemos a todos por participar! Como resultado de las discusiones, decidimos eliminar temporalmente ciertas características. ¡Así es como va a veces con una API experimental!

¡Pero esto no significa que hayan desaparecido para siempre! Eliminarlos ahora en esta etapa temprana nos da tiempo para tener discusiones separadas y volver a construir características basándonos en tu feedback, encontrando el equilibrio adecuado entre DX, mejores prácticas de accesibilidad, y defaults sensatos.

Estos items ya no están disponibles y deben eliminarse de tu código:

  • The title prop has been removed until we can settle on the correct balance between developer experience and accessibility. Please replace any title props on your components with aria-label: 
    <Logo title="My Company Logo" />
    <Logo aria-label="My Company Logo" />
  • Sprite mode has been temporarily removed while we consider a new implementation that addresses how this feature was being used in practice. This means that there are no longer multiple mode options, and all SVGs will be inline. All instances of mode must be removed from your project as you can no longer control a mode: 
    <Logo mode="inline" />
    <Logo /> // Always inline
    import { defineConfig } from 'astro'
    

    export default defineConfig({
      experimental: {
       svg: {
         mode: 'sprite'
       },
       svg: true
      }
    });
  • The default role is no longer applied due to developer feedback. Please add the appropriate role on each component individually as needed: 
    <Logo />
    <Logo role="img" /> // To keep the role that was previously applied by default
  • The size prop has been removed to better work in combination with viewBox and additional styles/attributes. Please replace size with explicit width and height attributes: 
    <Logo size={64} />
    <Logo width={64} height={64} />

Correcciones de bugs

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

Comunidad

El core team de Astro es:

Ben Holmes , Caleb Jasik , Chris Swithinbank , Emanuele Stoppa , Erika , Florian Lefebvre , Fuzzy , HiDeoo , Luiz Ferraz , Matt Kane , Matthew Phillips , Nate Moore , Reuben Tier , Sarah Rainsberger , and Yan Thomas .

Gracias a todos los demás contribuidores que ayudaron a hacer posible Astro 5.6, incluyendo Edward Brunetiere, Martin Trapp, Vardhaman Bhandari, Marocco2, Yury Michurin y Michael Stramel.

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