Precargar

Los tiempos de carga de las páginas juegan un papel importante en la usabilidad y el disfrute general de un sitio. La precarga opcional de Astro aporta los beneficios de las navegaciones de páginas casi instantáneas a su aplicación multipágina (MPA) a medida que sus visitantes interactúan con el sitio.

Habilitar la precarga

Puedes habilitar la precarga con la configuración prefetch:

astro.config.mjs

import { defineConfig } from 'astro/config';

export default defineConfig({
  prefetch: true
});

Un script de precarga se agregará a todas las páginas de tu sitio. Luego puedes agregar el atributo data-astro-prefetch a cualquier enlace <a /> en tu sitio para optar por la precarga. Cuando pasa el cursor sobre el enlace, el script buscará la página en segundo plano.

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

Toma en cuenta que la precarga solo funciona para los enlaces dentro de tu sitio, y no para los enlaces externos.

Configuración de precarga

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

Estrategias de precarga

Astro admite 4 estrategias de precarga para varios casos de uso:

• hover (por defecto): Precarga cuando pasas el cursor o te enfocas en el enlace.
• tap: Precarga justo antes de hacer clic en el enlace.
• viewport: Precarga cuando los enlaces entran en el viewport.
• load: Precarga todos los enlaces en la página después de que la página se ha cargado.

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

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

Cada estrategia está ajustada para precargar solo cuando sea necesario y ahorrar el ancho de banda de tus usuarios. Por ejemplo:

• Si un visitante está usando el modo ahorro de datos o tiene una conexión lenta, la precarga volverá a la estrategia tap.
• Desplazarse rápidamente sobre los enlaces no los precargará.

Estrategia de precarga predeterminada

La estrategia de precarga predeterminada al agregar el atributo data-astro-prefetch es hover. Para cambiarlo, puedes configurar prefetch.defaultStrategy en tu archivo astro.config.mjs:

astro.config.mjs

import { defineConfig } from 'astro/config';

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

Precargar todos los enlaces de forma predeterminada

Si quieres precargar todos los enlaces, incluidos los que no tienen 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
  }
});

Puedes optar por no precargar los enlaces individuales estableciendo data-astro-prefetch="false":

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

La estrategia de precarga predeterminada para todos los enlaces se puede cambiar con prefetch.defaultStrategy como se muestra en la sección Estrategia de precarga predeterminada.

Precarga programática

Como algunas navegaciones no siempre aparecen como enlaces <a />, también puedes precargar 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 el mismo modo de ahorro de datos y conexión lenta, por lo que solo precarga cuando sea necesario.

Para ignorar la detección de conexiones lentas, puedes utilizar la opción ignoreSlowConnection:

// Precargar incluso en el modo ahorro de datos o conexión lenta
prefetch('/about', { ignoreSlowConnection: true });

eagerness

Tipo: 'immediate' | 'eager' | 'moderate' | 'conservative'
Por defecto: 'immediate'

Agregado en: astro@5.6.0

Con la bandera experimental clientPrerender activada, puedes usar la opción eagerness en prefetch() para sugerirle al navegador con qué nivel de anticipación debería realizar el prefetch o prerender de los enlaces de destino.

Esto sigue la misma API descrita de la Speculation Rules API y, de forma predeterminada, se establece en immediate (la opción más agresiva). En orden decreciente de anticipación, las otras opciones son: eager, moderate y conservative.

La opción eagerness te permite equilibrar el beneficio de reducir los tiempos de espera con respecto al consumo de ancho de banda, memoria y CPU para los visitantes de tu sitio. Algunos navegadores, como Chrome, tienen límites para evitar una especulación excesiva (prerendering/prefetching de demasiados enlaces).

---
---
<script>
// Controlar el nivel de anticipación del prefetching con `experimental.clientPrerender`
import { prefetch } from 'astro:prefetch';
// Esta página consume muchos recursos
prefetch('/data-heavy-dashboard', { eagerness: 'conservative' });
// Esta página es fundamental en el recorrido del visitante
prefetch('/getting-started'); // defaults to `{ eagerness: 'immediate' }`
// Es posible que esta página no sea visitada
prefetch('/terms-of-service', { eagerness: 'moderate' });
</script>

Para usar prefetch() de forma programática con grandes conjuntos de enlaces, puedes establecer eagerness: 'moderate' para aprovechar las estrategias First In, First Out (FIFO) y las heurísticas del navegador, permitiendo que el navegador decida cuándo hacer prerender/prefetch de los enlaces 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 importar prefetch() solo en scripts del lado del cliente, ya que depende de las API del navegador.

Usar con View Transitions

Cuando usas el <ClientRouter /> de Astro en una página, la precarga también estará habilitada de forma predeterminada. Establece una configuración predeterminada de { prefetchAll: true } que habilita la precarga para todos los enlaces en la página.

Puedes personalizar la configuración de precarga en astro.config.mjs para anular la predeterminada. Por ejemplo:

astro.config.mjs

import { defineConfig } from 'astro/config';

export default defineConfig({
  // Desactiva la precarga por completo
  prefetch: false
});

astro.config.mjs

import { defineConfig } from 'astro/config';

export default defineConfig({
  // Mantén la precarga, pero solo precarga para los enlaces con `data-astro-prefetch`
  prefetch: {
    prefetchAll: false
  }
});

Compatibilidad con navegadores

El prefetching de Astro utiliza <link rel="prefetch"> si el navegador lo admite y, en caso contrario, recurre a la API fetch().

Los navegadores más comunes son compatibles con el prefetching de Astro, aunque con ligeras diferencias:

Chrome

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

También es totalmente compatible con <script type="speculationrules"> de la API Speculation Rules, que puede utilizarse para describir con más detalle las estrategias y reglas de prefetching, mejorando la experiencia de usuario para quienes utilicen Chrome.

Para aprovechar esta funcionalidad con prefetch(), deberás activar el experimento clientPrerender.

Firefox

Firefox admite <link rel="prefetch">, pero puede mostrar errores o fallar por completo:

• Sin una cabecera de caché explícita (por ejemplo, Cache-Control o Expires), el prefetching dará un error con NS_BINDING_ABORTED.
• Incluso si ocurre un error, si la respuesta tiene una cabecera ETag correcta, esta se reutilizará al navegar.
• De lo contrario, si se produce un error sin otras cabeceras de caché, el prefetch no funcionará.

Safari

Safari no admite <link rel="prefetch"> y recurrirá a la API fetch(), la cual requiere que se configuren cabeceras de caché (por ejemplo, Cache-Control, Expires y ETag). De lo contrario, el prefetch no funcionará.

Caso particular: las cabeceras ETag no funcionan en ventanas privadas.

Recomendaciones

Para garantizar la mejor compatibilidad con todos los navegadores, asegúrate de que tus páginas tengan las cabeceras de caché adecuadas.

En el caso de páginas estáticas o prerenderizadas, la cabecera ETag suele configurarse automáticamente por la plataforma de despliegue y se espera que funcione sin necesidad de ajustes adicionales.

Para páginas dinámicas o renderizadas en el servidor, configura tú mismo las cabeceras de caché apropiadas según el contenido de la página. Consulta la documentación de MDN sobre almacenamiento en caché HTTP para más información.

Migrando desde @astrojs/prefetch

La integración @astrojs/prefetch se ha eliminado en v3.5.0 y se eliminará por completo en el futuro. Utiliza las siguientes instrucciones para migrar a la precarga incorporada de Astro, que reemplaza esta integración.

1. Elimina la integración @astrojs/prefetch y habilita la configuración 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 las opciones de configuración de @astrojs/prefetch:

   • La integración obsoleta usaba la opción de configuración selector para especificar qué enlaces se deben precargar al ingresar al viewport.

     Agrega data-astro-prefetch="viewport" a estos enlaces individuales en su lugar:

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

   • La integración obsoleta usaba la opción de configuración intentSelector para especificar qué enlaces se deben precargar al pasar el mouse o enfocarse en ellos.

     Agrega data-astro-prefetch o data-astro-prefetch="hover" a estos enlaces individuales en su lugar:

     <!-- Puedes omitir el valor si `defaultStrategy` está establecido en `hover` (predeterminado) -->
     <a href="/about" data-astro-prefetch>
     
     <!-- De otra manera, puedes definir explícitamente la estrategia de precarga -->
     <a href="/about" data-astro-prefetch="hover">

   • La opción throttles de @astrojs/prefetch ya no es necesaria, ya que la nueva función de precarga programática programará y precargará automáticamente de forma óptima.