Carregamento de Assets - Pré-carregue fontes, scripts e stylesheets com APIs do React DOM

Receita

import { prefetchDNS, preconnect, preload, preinit } from "react-dom";
 
function App() {
  // Eagerly load and execute a script
  preinit("https://cdn.example.com/analytics.js", { as: "script" });
 
  // Preload a font (download early, use later)
  preload("https://fonts.example.com/inter.woff2", {
    as: "font",
    type: "font/woff2",
    crossOrigin: "anonymous",
  });
 
  // Preload a stylesheet
  preload("https://cdn.example.com/theme.css", { as: "style" });
 
  // DNS prefetch for a domain you will request later
  prefetchDNS("https://api.example.com");
 
  // Preconnect (DNS + TCP + TLS) for a domain you will request soon
  preconnect("https://images.example.com");
 
  return <main>{/* ... */}</main>;
}

Quando usar isso: Use essas APIs para melhorar o desempenho do carregamento inicial da página e da navegação no lado do cliente, informando ao navegador sobre os recursos de que ele precisará antes que o React renderize os componentes que os utilizam.

Exemplo Funcional

// A page that preloads all critical resources for optimal performance
import { Suspense } from "react";
import { preload, preinit, preconnect } from "react-dom";
 
// Preload critical resources at the module level (runs once on import)
preconnect("https://api.myapp.com");
preload("/fonts/brand-bold.woff2", { as: "font", type: "font/woff2", crossOrigin: "anonymous" });
preload("/fonts/brand-regular.woff2", { as: "font", type: "font/woff2", crossOrigin: "anonymous" });
 
function CriticalCSS() {
  return (
    <>
      {/* React deduplicates and manages stylesheet loading order via precedence */}
      <link rel="stylesheet" href="/styles/reset.css" precedence="reset" />
      <link rel="stylesheet" href="/styles/base.css" precedence="default" />
      <link rel="stylesheet" href="/styles/theme.css" precedence="high" />
    </>
  );
}
 
function HeavyWidget() {
  // Preinit a script needed by this widget
  preinit("/scripts/chart-library.js", { as: "script" });
 
  return (
    <div className="widget">
      <h2>Sales Dashboard</h2>
      <div id="chart-container" />
    </div>
  );
}
 
function ImageGallery({ images }: { images: { src: string; alt: string }[] }) {
  // Preload the first few images for instant display
  images.slice(0, 3).forEach((img) => {
    preload(img.src, { as: "image" });
  });
 
  return (
    <div className="grid grid-cols-3 gap-4">
      {images.map((img, i) => (
        <img
          key={i}
          src={img.src}
          alt={img.alt}
          loading={i < 3 ? "eager" : "lazy"}
        />
      ))}
    </div>
  );
}
 
export default function DashboardPage() {
  return (
    <>
      <CriticalCSS />
      <title>Dashboard | MyApp</title>
 
      <header>
        <h1>Dashboard</h1>
      </header>
 
      <Suspense fallback={<p>Loading widget...</p>}>
        <HeavyWidget />
      </Suspense>
 
      <Suspense fallback={<p>Loading gallery...</p>}>
        <ImageGallery
          images={[
            { src: "/images/product-1.jpg", alt: "Product 1" },
            { src: "/images/product-2.jpg", alt: "Product 2" },
            { src: "/images/product-3.jpg", alt: "Product 3" },
            { src: "/images/product-4.jpg", alt: "Product 4" },
            { src: "/images/product-5.jpg", alt: "Product 5" },
            { src: "/images/product-6.jpg", alt: "Product 6" },
          ]}
        />
      </Suspense>
    </>
  );
}

O que isso demonstra:

• preconnect estabelecendo conexões antecipadas com domínios de API
• preload para fontes no nível do módulo (antes que qualquer componente seja renderizado)
• <link rel="stylesheet" precedence={}> para CSS ordenado e deduplicado
• preinit carregando antecipadamente um script de terceiros dentro de um componente
• preload para imagens para acelerar a renderização acima da dobra
• Limites de Suspense em torno de componentes pesados para streaming

Mergulho Profundo

Como Funciona

• preload(href, options) -- Insere uma tag <link rel="preload"> no documento. O navegador baixa o recurso com alta prioridade, mas não o executa nem o aplica. Use para fontes, imagens, stylesheets e scripts que você precisará em breve.
• preinit(href, options) -- Baixa e executa/aplica o recurso imediatamente. Para scripts, isso significa que o script é executado. Para stylesheets, isso significa que o CSS é aplicado. Use quando você precisar que o recurso esteja ativo imediatamente.
• prefetchDNS(href) -- Insere uma dica <link rel="dns-prefetch">. O navegador resolve o nome de domínio antecipadamente. Opção mais barata -- use quando você pode solicitar deste domínio.
• preconnect(href) -- Insere um <link rel="preconnect">. O navegador executa o handshake DNS + TCP + TLS antecipadamente. Use quando você definitivamente solicitará deste domínio em breve.
• Todas as quatro APIs podem ser chamadas em qualquer lugar -- dentro de componentes, manipuladores de eventos, escopo de módulo ou até mesmo efeitos. O React deduplica chamadas com o mesmo href.
• Durante SSR, essas chamadas emitem as tags <link> apropriadas no <head> do HTML e como dicas antecipadas (103 Early Hints) se o servidor suportar.
• Suspense de Stylesheet -- <link rel="stylesheet" precedence={}> informa ao React para gerenciar o stylesheet. O React suspenderá a renderização do componente até que o stylesheet seja carregado, evitando um flash de conteúdo não estilizado.

Variações

Pré-carregamento ao passar o mouse (preditivo):

"use client";
 
import { preload } from "react-dom";
import Link from "next/link";
 
function NavLink({ href, children }: { href: string; children: React.ReactNode }) {
  function handleMouseEnter() {
    // Preload the page's CSS and hero image when user hovers
    preload(`/styles${href}.css`, { as: "style" });
    preload(`/images${href}-hero.jpg`, { as: "image" });
  }
 
  return (
    <Link href={href} onMouseEnter={handleMouseEnter}>
      {children}
    </Link>
  );
}

Pré-carregamento condicional baseado na viewport:

"use client";
 
import { useEffect } from "react";
import { preload } from "react-dom";
 
function AdaptiveLoader() {
  useEffect(() => {
    const connection = (navigator as any).connection;
    if (connection?.effectiveType === "4g") {
      // Only preload heavy resources on fast connections
      preload("/videos/hero.mp4", { as: "video" });
      preload("/fonts/display.woff2", { as: "font", crossOrigin: "anonymous" });
    }
  }, []);
 
  return null;
}

Pré-carregamento no nível do módulo (executa na importação):

import { preconnect, preload } from "react-dom";
 
// These execute when the module is imported, before any component renders
preconnect("https://cdn.example.com");
preload("https://cdn.example.com/critical.css", { as: "style" });
 
export default function Page() {
  return <div>Content that needs cdn.example.com resources</div>;
}

Notas TypeScript

• Todas as quatro funções são importadas de "react-dom".
• preload(href: string, options: { as: string; crossOrigin?: string; type?: string; fetchPriority?: "high" | "low" | "auto" }).
• preinit(href: string, options: { as: "script" | "style"; crossOrigin?: string; fetchPriority?: "high" | "low" | "auto"; nonce?: string }).
• prefetchDNS(href: string) e preconnect(href: string, options?: { crossOrigin?: string }) têm opções mínimas.
• O atributo precedence em <link rel="stylesheet"> é tipado como string.

Armadilhas

• Pré-carregar muitos recursos -- Navegadores têm limites para conexões simultâneas. Pré-carregar tudo é contraproducente. Correção: Pré-carregue apenas os recursos que são críticos para a experiência acima da dobra.
• preinit executa scripts imediatamente -- Se o script tiver efeitos colaterais ou depender de elementos DOM que ainda não foram renderizados, ele pode falhar. Correção: Use preload em vez disso e adicione uma tag <script> quando o DOM estiver pronto, ou certifique-se de que o script lida com DOM ausente graciosamente.
• Pré-carregamento de fonte sem crossOrigin -- Fontes carregadas via preload devem especificar crossOrigin: "anonymous" mesmo para fontes same-origin, de acordo com a especificação Fetch. Correção: Sempre inclua crossOrigin: "anonymous" para pré-carregamentos de fontes.
• Stylesheet sem precedence não é gerenciado -- Se você omitir precedence de um <link rel="stylesheet">, o React não o deduplica nem suspende por ele. Correção: Adicione precedence a todos os links de stylesheet que você deseja que o React gerencie.
• Tempo de preload em SSR vs. cliente -- Durante o SSR, as dicas de preload aparecem no HTML inicial. Durante a navegação do cliente, elas são injetadas dinamicamente. A diferença de tempo pode afetar as características de desempenho. Correção: Teste os caminhos de SSR e navegação do cliente.

Alternativas

FAQs

preload("/fonts/brand.woff2", {
  as: "font",
  type: "font/woff2",
  crossOrigin: "anonymous", // required for all fonts
});

function NavLink({ href, children }) {
  function handleMouseEnter() {
    preload(`/styles${href}.css`, { as: "style" });
    preload(`/images${href}-hero.jpg`, { as: "image" });
  }
  return (
    <a href={href} onMouseEnter={handleMouseEnter}>
      {children}
    </a>
  );
}

useEffect(() => {
  const conn = (navigator as any).connection;
  if (conn?.effectiveType === "4g") {
    preload("/videos/hero.mp4", { as: "video" });
    preload("/fonts/display.woff2", {
      as: "font",
      crossOrigin: "anonymous",
    });
  }
}, []);

preload(href: string, options: {
  as: string;
  crossOrigin?: string;
  type?: string;
  fetchPriority?: "high" | "low" | "auto";
}): void;
 
preinit(href: string, options: {
  as: "script" | "style";
  crossOrigin?: string;
  fetchPriority?: "high" | "low" | "auto";
  nonce?: string;
}): void;

Relacionado

• Metadados -- Renderizando tags de título, meta e link em componentes
• Server Components -- Pré-carregando recursos durante a renderização do servidor
• Visão Geral -- Lista completa de recursos do React 19