Pular para o conteúdo

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

Seção intitulada Habilitar o pré-carregamento

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

astro.config.js
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

Seção intitulada 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

Seção intitulada 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

Seção intitulada 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:

astro.config.js
import { defineConfig } from 'astro/config';


export default defineConfig({
  prefetch: {
    defaultStrategy: 'viewport'
  }
})
Seção intitulada 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:

astro.config.js
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

Seção intitulada 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

Seção intitulada 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:

astro.config.js
import { defineConfig } from 'astro/config';


export default defineConfig({
  // Desabilita o pré-carregamento completamente
  prefetch: false
})
astro.config.js
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

Seção intitulada 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.

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

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

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

  2. 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:

      <!-- Você pode omitir o valor se `defaultStrategy` estiver configurado como `hover` (padrão) -->
      <a href="/sobre" data-astro-prefetch>
      

      <!-- Caso contrário, você pode definir explicitamente a estratégia de pré-carregamento -->
      <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.