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.mjs

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 carregará a página em segundo plano.

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

Note 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 banda 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 substituto.
• Passar o mouse rapidamente ou rolar a página sobre links não causará o pré-carregamento.

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

astro.config.mjs

import { defineConfig } from 'astro/config';

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

Pré-carregar todos os links por padrão

Seção intitulada Pré-carregar todos os links por padrão

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

astro.config.mjs

import { defineConfig } from 'astro/config';

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

Você pode 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 mostrado na seção Estratégia padrão de pré-carregamento.

Pré-carregar programaticamente

Seção intitulada Pré-carregar programaticamente

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

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

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

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

A API prefetch() inclui a mesma detecção de modo de economia de dados e de conexão lenta para que o pré-carregamento ocorra somente 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 de conexão lenta
prefetch('/sobre', { ignoreSlowConnection: true });

Certifique-se de apenas importar o prefetch() em scripts do lado do cliente, pois ele depende de APIs do navegador.

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 define a configuração padrão de { 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.mjs para sobrescrever o padrão. Por exemplo:

astro.config.mjs

import { defineConfig } from 'astro/config';

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

astro.config.mjs

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
  }
});

Suporte de navegadores

Seção intitulada Suporte de navegadores

O pré-carregamento do Astro usa <link rel="prefetch"> quando suportado pelo navegador, e substitui com a API fetch() caso contrário.

Os navegadores mais comuns suportam o pré-carregamento do Astro com diferenças sutis:

Chrome

Seção intitulada Chrome

Chrome suporta <link rel="prefetch">. Pré-carregamento funciona como esperado.

Firefox

Seção intitulada Firefox

Firefox suporta <link rel="prefetch"> mas pode mostrar erros ou falhar inteiramente:

• Sem um cabeçalho de cache explícito (e.g. Cache-Control ou Expires), o pré-carregamento causará um erro com NS_BINDING_ABORTED.
• Mesmo eo evento de um erro, se a resposta tiver um cabeçalho ETag adequado, ele será reusado na navegação.
• Caso contrário, se houver erros sem outros cabeçalhos de cache, o pré-carregamento não funcionará.

Safari

Seção intitulada Safari

Safari não suporta <link rel="prefetch"> e substituirá com a API fetch() que exige cabeçalhos de cache definidos (e.g. Cache-Control, Expires, e ETag). Caso contrário, o pré-carregamento não funcionará.

Caso isolado: Cabeçalhos ETag não funcionam em janelas privadas.

Recomendações

Seção intitulada Recomendações

Para melhor suportar todos os navegadores, certifique-se de que suas páginas possuem os cabeçalhos de cache adequados.

Para páginas estáticas ou pré-renderizadas, o cabeçalho ETag é muitas vezes definido automaticamente pela plataforma de implantação e é esperado que funcione prontamente.

Para páginas renderizadas dinamicamente ou no lado do servidor, defina os cabeçalhos de cache apropriados baseado no conteúdo da página. Visite a documentação sobre cache HTTP da MDN para mais informações.

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

   astro.config.mjs

   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 usava a opção de configuração selector para especificar quais links deveriam ser pré-carregados quando entrassem na janela de exibição.

     Em vez disso, adicione data-astro-prefetch="viewport" a esses links individualmente:

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

   • A integração descontinuada usava a opção de configuração intentSelector para especificar quais links deveriam ser pré-carregados quando o usuário passasse o mouse ou atribuísse foco.

     Em vez disso, adicione data-astro-prefetch ou data-astro-prefetch="hover" a esses links individualmente:

     <!-- Você pode omitir o valor se `defaultStrategy` estiver definido 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 planejar e pré-carregar forma otimizada.