원문: https://react.dev/reference/react-dom/preload

preload

preload는 스타일시트, 폰트, 외부 스크립트 등 앞으로 사용할 리소스를 미리 받아올 수 있게 해줍니다.

preload("https://example.com/font.woff2", {as: "font"});

레퍼런스
- preload(href, options)
사용법
- 렌더링 시 미리 받아오기
- 이벤트 핸들러에서 미리 받아오기

레퍼런스

`preload(href, options)`

리소스를 미리 받아오려면 react-dom에서 preload 함수를 호출하세요.

import { preload } from 'react-dom';

function AppRoot() {
  preload("https://example.com/font.woff2", {as: "font"});
  // ...
}

preload 함수는 브라우저에 해당 리소스를 즉시 다운로드하라는 힌트를 제공합니다.

파라미터

href: 문자열. 다운로드할 리소스의 URL입니다.
options: 객체. 다음 속성을 포함할 수 있습니다:
- as: 문자열, 필수. 리소스의 타입. audio, document, embed, fetch, font, image, object, script, style, track, video, worker 중 하나입니다.
- crossOrigin: 문자열. CORS 정책(anonymous, use-credentials). as가 fetch일 때 필수입니다.
- referrerPolicy: 문자열. 리소스를 가져올 때 보낼 Referrer 헤더(no-referrer-when-downgrade(기본값), no-referrer, origin, origin-when-cross-origin, unsafe-url).
- integrity: 문자열. 리소스의 무결성 검증용 해시.
- type: 문자열. 리소스의 MIME 타입.
- nonce: 문자열. CSP(Content Security Policy)에서 허용할 난수값.
- fetchPriority: 문자열. 리소스의 다운로드 우선순위(auto, high, low).
- imageSrcSet: 문자열. as: "image"일 때만 사용. 이미지의 소스셋.
- imageSizes: 문자열. as: "image"일 때만 사용. 이미지의 크기.

반환값

preload는 아무것도 반환하지 않습니다.

주의사항

동일한 리소스에 대해 여러 번 호출해도 한 번 호출한 것과 동일한 효과입니다. 단, as가 image일 때는 href, imageSrcSet, imageSizes가 모두 같아야 동일하게 간주됩니다.
브라우저 환경에서는 컴포넌트 렌더링, Effect, 이벤트 핸들러 등 언제든 호출할 수 있습니다.
서버 사이드 렌더링 또는 Server Components에서는 컴포넌트 렌더링 중이거나 렌더링에서 파생된 비동기 컨텍스트에서만 효과가 있습니다. 그 외의 호출은 무시됩니다.

사용법

렌더링 시 미리 받아오기

컴포넌트나 자식이 특정 리소스를 사용할 것이 확실하다면, 컴포넌트 렌더링 시 preload를 호출하세요.

예시: 외부 스크립트 미리 받아오기

import { preload } from 'react-dom';

function AppRoot() {
  preload("https://example.com/script.js", {as: "script"});
  return ...;
}

만약 스크립트를 즉시 실행하고 싶다면 preload 대신 preinit을 사용하세요. ESM 모듈을 미리 받아오려면 preloadModule을 사용하세요.

예시: 스타일시트 미리 받아오기

import { preload } from 'react-dom';

function AppRoot() {
  preload("https://example.com/styles.css", {as: "style"});
  return ...;
}

예시: 폰트 미리 받아오기

import { preload } from 'react-dom';

function AppRoot() {
  preload("https://example.com/font.woff2", {as: "font"});
  return ...;
}

예시: 이미지 미리 받아오기

import { preload } from 'react-dom';

function AppRoot() {
  preload("https://example.com/image.png", {as: "image", imageSrcSet: "...", imageSizes: "..."});
  return ...;
}

이벤트 핸들러에서 미리 받아오기

페이지나 상태 전환 전에 외부 리소스가 필요할 것이 예상된다면, 이벤트 핸들러에서 preload를 호출해 미리 다운로드를 시작할 수 있습니다.

import { preload } from 'react-dom';

function CallToAction() {
  const onClick = () => {
    preload("https://example.com/wizardStyles.css", {as: "style"});
    startWizard();
  }
  return (
    <button onClick={onClick}>Start Wizard</button>
  );
}