Pré-carregamento

O tempo de carregamento das páginas gera grande impacto na usabilidade e no nível de satisfação de um site. A opção de pré-carregamento do Astro traz os benefícios de uma navegação quase instantânea à sua aplicação multi-página (MPA) conforme os seus visitantes interagem com o site.

Habilitar o pré-carregamento

Você pode habilitar o pré-carregamento com a configuração prefetch:

import { defineConfig } from 'astro/config';

export default defineConfig({
  prefetch: true
})

Um script de pré-carregamento será adicionado a todas as páginas do seu site. Você pode então adicionar o atributo data-astro-prefetch a qualquer link <a /> do seu site e optar pelo pré-carregamento. Quando você passar o mouse sobre um link, o script irá carregar a página em segundo plano.

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

Perceba que o pré-carregamento funciona apenas para links do seu próprio site, e não para links externos.

Configuração de pré-carregamento

A configuração de prefetch também aceita um objeto opcional para customizar o pré-carregamento.

Estratégias de pré-carregamento

O Astro suporta 4 estratégias de pré-carregamento para diversos casos de uso:

hover (padrão): Pré-carrega quando você passa o mouse sobre o link ou atribui foco a ele.
tap: Pré-carrega logo antes de você clicar no link.
viewport: Pré-carrega assim que os links entrarem na janela de exibição.
load: Pré-carrega todos os links da página assim que ela é carregada.

Você pode especificar uma estratégia para um link individual através do atributo data-astro-prefetch:

<a href="/sobre" data-astro-prefetch="tap">Sobre</a>

Cada estratégia é ajustada para pré-carregar somente quando necessário e economizar a conexão dos seus usuários. Por exemplo:

Se um visitante estiver usando o modo de economia de dados ou possui uma conexão lenta, o pré-carregamento utilizará a estratégia tap como fallback.
Passar o mouse rapidamente ou rolar a página sobre links não causará o pré-carregamento.
Links que utilizarem as estratégias viewport ou load serão pré-carregadas com menor prioridade para evitar gargalo de rede.

Estratégia padrão de pré-carregamento

A estratégia padrão de pré-carregamento do atributo data-astro-prefetch é hover. Para alterá-la, você pode configurar o atributo prefetch.defaultStrategy no seu arquivo astro.config.js:

import { defineConfig } from 'astro/config';

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

Pré-carregar todos os links por padrão

Se você quiser pré-carregar todos os links, incluindo os que não possuem o atributo data-astro-prefetch, você pode configurar prefetch.prefetchAll para true:

import { defineConfig } from 'astro/config';

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

Você pode, então, escolher não pré-carregar links individualmente adicionando data-astro-prefetch="false":

<a href="/sobre" data-astro-prefetch="false">Sobre</a>

A estratégia de pré-carregamento padrão pode ser alterada para todos os links com prefetch.defaultStrategy, como foi mostrado na seção Estratégia padrão de pré-carregamento.

Pré-carregar programaticamente

Como nem sempre a navegação será exibida na forma de links <a />, você pode também pré-carregar páginas programaticamente com a API prefetch() do módulo astro:prefetch:

<button id="botao">Clique aqui</button>

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

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

Você pode também configurar a prioridade de pré-carregamento através da opção with:

// Pré-carregamento com `fetch()` possui prioridade mais alta.
prefetch('/sobre', { with: 'fetch' });

// Pré-carregamento com `<link rel="prefetch">` possui prioridade mais baixa
// e é manualmente agendada pelo navegador. (padrão)
prefetch('/sobre', { with: 'link' });

A API prefetch() inclui as mesmas detecções de modo de economia de dados e de conexão lenta de forma que o pré-carregamento ocorra apenas quando é necessário.

Para ignorar a detecção de conexão lenta, você pode utilizar a opção ignoreSlowConnection:

// Pré-carrega mesmo no modo de economia de dados ou conexão lenta
prefetch('/sobre', { ignoreSlowConnection: true });

Tome o cuidado de apenas utilizar o prefetch() em scripts do lado do cliente, pois ele depende das APIs do navegador para funcionar.

Utilizando com Transições de Visualização

Quando você usa Transições de Visualização em uma página, o pré-carregamento também será habilitado por padrão. Isso configura o atributo { prefetchAll: true }, que habilita o pré-carregamento para todos os links da página.

Você pode customizar a configuração de pré-carregamento no arquivo astro.config.js para sobrescrever a configuração padrão. Por exemplo:

import { defineConfig } from 'astro/config';

export default defineConfig({
  // Desabilita o pré-carregamento completamente
  prefetch: false
})

import { defineConfig } from 'astro/config';

export default defineConfig({
  // Mantém o pré-carregamento, mas pré-carrega apenas links com `data-astro-prefetch`
  prefetch: {
    prefetchAll: false
  }
})

Migrando de `@astrojs/prefetch`

A integração @astrojs/prefetch foi descontinuada na versão v3.5.0 e eventualmente será removida completamente. Siga as seguintes instruções para migrar para o pré-carregamento integrado do Astro, que substitui essa integração.

Remova a integração @astrojs/prefetch e habilite a configuração prefetch em astro.config.js:

import { defineConfig } from 'astro/config';
import prefetch from '@astrojs/prefetch';

export default defineConfig({
  integrations: [prefetch()],
  prefetch: true
})

Converta as opções de configuração do @astro/prefetch:
- A integração descontinuada utilizava a opção de configuração selector para especificar quais links deveriam ser pré-carregados quando entrassem na janela de exibição (viewport).
  
  Ao invés disso, adicione data-astro-prefetch="viewport" a esses links individualmente:
```
<a href="/sobre" data-astro-prefetch="viewport">
```
- A integração descontinuada utilizava a opção de configuração intentSelector para especificar quais links deveriam ser pré-carregados quando o usuário passasse o mouse sobre ele, ou entrasse em foco.
  
  Ao invés disso, adicione data-astro-prefetch ou data-astro-prefetch="hover" a esses links individualmente:
```

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


<a href="/sobre" data-astro-prefetch="hover">
```
- A opção throttles do @astrojs/prefetch não é mais necessária, pois o novo recurso de pré-carregamento irá automaticamente agendar e pré-carregar de forma otimizada.