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
Sección titulada «Habilitar la precarga»Puedes habilitar la precarga con la configuración prefetch
:
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
Sección titulada «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
Sección titulada «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
Sección titulada «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
:
import { defineConfig } from 'astro/config';
export default defineConfig({ prefetch: { defaultStrategy: 'viewport' }});
Precargar todos los enlaces de forma predeterminada
Sección titulada «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
:
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
Sección titulada «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 lentaprefetch('/about', { ignoreSlowConnection: true });
eagerness
Sección titulada «eagerness»Tipo: 'immediate' | 'eager' | 'moderate' | 'conservative'
Por defecto: 'immediate'
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 recursosprefetch('/data-heavy-dashboard', { eagerness: 'conservative' });// Esta página es fundamental en el recorrido del visitanteprefetch('/getting-started'); // defaults to `{ eagerness: 'immediate' }`// Es posible que esta página no sea visitadaprefetch('/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
Sección titulada «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:
import { defineConfig } from 'astro/config';
export default defineConfig({ // Desactiva la precarga por completo prefetch: false});
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
Sección titulada «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 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
Sección titulada «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
oExpires
), el prefetching dará un error conNS_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 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
Sección titulada «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
Sección titulada «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.
-
Elimina la integración
@astrojs/prefetch
y habilita la configuraciónprefetch
enastro.config.mjs
:astro.config.mjs import { defineConfig } from 'astro/config';import prefetch from '@astrojs/prefetch';export default defineConfig({integrations: [prefetch()],prefetch: true}); -
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
odata-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.
-