Prefetch

Los tiempos de carga de página juegan un papel importante en la usabilidad y el disfrute general de un sitio. El prefetching opt-in de Astro trae los beneficios de navegaciones de página casi instantáneas a tu aplicación multi-página (MPA) a medida que tus visitantes interactúan con el sitio.

Habilitar prefetching

Puedes habilitar el prefetching con la configuración de prefetch:

astro.config.mjs

import { defineConfig } from 'astro/config';

export default defineConfig({
  prefetch: true
});

Se añadirá un script de prefetching a todas las páginas de tu sitio. Luego puedes añadir el atributo data-astro-prefetch a cualquier link de <a /> en tu sitio para optar por el prefetching. Cuando pases el cursor sobre el link, el script obtendrá la página en segundo plano.

<a href="/about" data-astro-prefetch>

Ten en cuenta que el prefetching solo funciona para links dentro de tu sitio, y no para links externos.

Configuración de prefetching

La configuración de prefetch también acepta un objeto de opciones para personalizar aún más el prefetching.

Estrategias de prefetching

Astro soporta 4 estrategias de prefetching para varios casos de uso:

• hover (por defecto): Pre-carga cuando pasas el cursor sobre el link o lo enfocas.
• tap: Pre-carga justo antes de hacer clic en el link.
• viewport: Pre-carga a medida que los links entran en el viewport.
• load: Pre-carga todos los links de la página después de que la página se carga.

Puedes especificar una estrategia para un link individual pasándola al atributo data-astro-prefetch:

<a href="/about" data-astro-prefetch="tap">About</a>

Cada estrategia está afinada para solo pre-cargar cuando es necesario y ahorrar el ancho de banda de tus usuarios. Por ejemplo:

• Si un visitante está usando modo de ahorro de datos o tiene una conexión lenta, el prefetching recurrirá a la estrategia tap.
• Pasar el cursor rápidamente o desplazarse sobre links no los pre-cargará.

Estrategia de prefetching por defecto

La estrategia de prefetching por defecto al añadir el atributo data-astro-prefetch es hover. Para cambiarla, puedes configurar prefetch.defaultStrategy en tu archivo astro.config.mjs:

astro.config.mjs

import { defineConfig } from 'astro/config';

export default defineConfig({
  prefetch: {
    defaultStrategy: 'viewport'
  }
});

Pre-cargar todos los links por defecto

Si quieres pre-cargar todos los links, incluyendo aquellos sin el atributo data-astro-prefetch, puedes establecer prefetch.prefetchAll en true:

astro.config.mjs

import { defineConfig } from 'astro/config';

export default defineConfig({
  prefetch: {
    prefetchAll: true
  }
});

Luego puedes optar por no pre-cargar links individuales estableciendo data-astro-prefetch="false":

<a href="/about" data-astro-prefetch="false">About</a>

La estrategia de prefetching por defecto para todos los links puede cambiarse con prefetch.defaultStrategy como se muestra en la sección de estrategia de prefetching por defecto.

Pre-cargar programáticamente

Como algunas navegaciones podrían no aparecer siempre como links <a />, también puedes pre-cargar programáticamente con la API prefetch() del módulo astro:prefetch:

<button id="btn">Click me</button>

<script>
  import { prefetch } from 'astro:prefetch';

  const btn = document.getElementById('btn');
  btn.addEventListener('click', () => {
    prefetch('/about');
  });
</script>

La API prefetch() incluye la misma detección de modo de ahorro de datos y conexión lenta para que solo pre-cargue cuando sea necesario.

Para ignorar la detección de conexión lenta, puedes usar la opción ignoreSlowConnection:

// Prefetch even on data saver mode or slow connection
prefetch('/about', { ignoreSlowConnection: true });

eagerness

Type: 'immediate' | 'eager' | 'moderate' | 'conservative'
Default: 'immediate'

Añadido en: astro@5.6.0

Con el flag experimental clientPrerender habilitado, puedes usar la opción eagerness en prefetch() para sugerir al navegador con qué eagerness debería pre-cargar/pre-renderizar los destinos de los links.

Esto sigue la misma API descrita en la Speculation Rules API y por defecto es immediate (la opción más eager). En orden decreciente de eagerness, las otras opciones son eager, moderate, y conservative.

La opción eagerness te permite equilibrar el beneficio de reducir los tiempos de espera contra los costes de ancho de banda, memoria y CPU para los visitantes de tu sitio. Algunos navegadores, como Chrome, tienen límites para proteger contra sobre-especulación (pre-renderizar/pre-cargar demasiados links).

---
---
<script>
// Control prefetching eagerness with `experimental.clientPrerender`
import { prefetch } from 'astro:prefetch';

// This page is resource-intensive
prefetch('/data-heavy-dashboard', { eagerness: 'conservative' });

// This page is critical to the visitor's journey
prefetch('/getting-started'); // defaults to `{ eagerness: 'immediate' }`

// This page may not be visited
prefetch('/terms-of-service', { eagerness: 'moderate' });
</script>

Para usar prefetch() programáticamente con grandes conjuntos de links, puedes establecer eagerness: 'moderate' para aprovechar las estrategias First In, First Out (FIFO) y la heurística del navegador para dejar que el navegador decida cuándo pre-renderizar/pre-cargarlos y en qué orden:

<a class="link-moderate" href="/nice-link-1">A Nice Link 1</a>
<a class="link-moderate" href="/nice-link-2">A Nice Link 2</a>
<a class="link-moderate" href="/nice-link-3">A Nice Link 3</a>
<a class="link-moderate" href="/nice-link-4">A Nice Link 4</a>
...
<a class="link-moderate" href="/nice-link-20">A Nice Link 20</a>

<script>
  import { prefetch } from 'astro:prefetch';

  const linkModerate = document.getElementsByClassName('link-moderate');
  linkModerate.forEach((link) => prefetch(link.getAttribute('href'), {eagerness: 'moderate'}));

</script>

Asegúrate de solo importar prefetch() en scripts del lado del cliente ya que depende de APIs del navegador.

Uso con View Transitions

Cuando usas el <ClientRouter /> de Astro en una página, el prefetching también se habilitará por defecto. Establece una configuración por defecto de { prefetchAll: true } que habilita el prefetching para todos los links de la página.

Puedes personalizar la configuración de prefetching en astro.config.mjs para sobrescribir el valor por defecto. Por ejemplo:

astro.config.mjs

import { defineConfig } from 'astro/config';

export default defineConfig({
  // Disable prefetch completely
  prefetch: false
});

astro.config.mjs

import { defineConfig } from 'astro/config';

export default defineConfig({
  // Keep prefetch, but only prefetch for links with `data-astro-prefetch`
  prefetch: {
    prefetchAll: false
  }
});

Soporte de navegadores

El prefetching de Astro usa <link rel="prefetch"> si es soportado por el navegador, y recurre a la API fetch() en caso contrario.

Los navegadores más comunes soportan el prefetching de Astro con diferencias sutiles:

Chrome

Chrome soporta <link rel="prefetch">. El prefetching funciona como se espera.

También soporta completamente <script type="speculationrules"> de la Speculation Rules API, que puede usarse para describir más detalladamente estrategias y reglas de prefetching, mejorando la experiencia de usuario para tus usuarios de Chrome. Necesitarás habilitar el experimento clientPrerender para utilizar esta funcionalidad con prefetch()

Firefox

Firefox soporta <link rel="prefetch"> pero puede mostrar errores o fallar completamente:

• Sin un encabezado de caché explícito (p. ej. Cache-Control o Expires), el prefetching dará error con NS_BINDING_ABORTED.
• Incluso en caso de error, si la respuesta tiene un encabezado ETag apropiado, se reutilizará en la navegación.
• De lo contrario, si da error sin otros encabezados de caché, el prefetching no funcionará.

Safari

Safari no soporta <link rel="prefetch"> y recurrirá a la API fetch() que requiere que se establezcan encabezados de caché (p. ej. Cache-Control, Expires, y ETag). De lo contrario, el prefetching no funcionará.

Caso especial: los encabezados ETag no funcionan en ventanas privadas.

Recomendaciones

Para soportar mejor todos los navegadores, asegúrate de que tus páginas tengan los encabezados de caché apropiados.

Para páginas estáticas o pre-renderizadas, el encabezado ETag suele ser establecido automáticamente por la plataforma de despliegue y se espera que funcione out-of-the-box.

Para páginas dinámicas y renderizadas en el servidor, establece tú mismo los encabezados de caché apropiados basándote en el contenido de la página. Visita la documentación de MDN sobre caché HTTP para más información.

Migrar desde @astrojs/prefetch

La integración @astrojs/prefetch fue deprecada en v3.5.0 y ya no se mantiene. Usa las siguientes instrucciones para migrar al prefetching integrado de Astro que reemplaza esta integración.

1. Elimina la integración @astrojs/prefetch y habilita la configuración de prefetch en astro.config.mjs:

   astro.config.mjs

   import { defineConfig } from 'astro/config';
   import prefetch from '@astrojs/prefetch';
   
   export default defineConfig({
     integrations: [prefetch()],
     prefetch: true
   });

2. Convierte desde las opciones de configuración de @astrojs/prefetch:

   • La integración deprecada usaba la opción de configuración selector para especificar qué links debían pre-cargarse al entrar en el viewport.

     Añade data-astro-prefetch="viewport" a estos links individuales en su lugar.

     <a href="/about" data-astro-prefetch="viewport">

   • La integración deprecada usaba la opción de configuración intentSelector para especificar qué links debían pre-cargarse cuando se pasaba el cursor sobre ellos o se enfocaban.

     Añade data-astro-prefetch o data-astro-prefetch="hover" a estos links individuales en su lugar:

     <!-- You can omit the value if `defaultStrategy` is set to `hover` (default) -->
     <a href="/about" data-astro-prefetch>
     
     <!-- Otherwise, you can explicitly define the prefetch strategy -->
     <a href="/about" data-astro-prefetch="hover">

   • La opción throttles de @astrojs/prefetch ya no es necesaria ya que la nueva característica de prefetching programará y pre-cargará automáticamente de forma óptima.