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:

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

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

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

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

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

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

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

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

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

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

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.