preload

01무엇

preload는 곧 쓸 리소스를 미리 내려받게 하는 API다. 스타일시트, 폰트, 스크립트, 이미지 같은 것을 브라우저에 알려 다운로드를 일찍 시작시킨다.

인자는 리소스 URL인 href와 옵션 객체다. 옵션의 as는 필수로, 리소스 종류(style, script, font, image, fetch 등)를 지정한다.

import { preload } from 'react-dom'

preload('https://example.com/style.css', { as: 'style' })

옵션에는 crossOrigin(as가 "fetch"면 필수), integrity, type, nonce, fetchPriority가 있고, as: "image"일 때만 쓰는 imageSrcSet·imageSizes가 있다. 반환값은 없다.

02무슨 일이 일어나나

preload는 리소스를 내려받기만 한다. 실행하거나 문서에 꽂지는 않는다. 이 점이 preinit과 다르다. preinit은 내려받고 곧바로 실행·삽입까지 한다. 스타일시트를 바로 적용하거나 스크립트를 즉시 실행하려면 preinit, 다운로드만 앞당기려면 preload다.

같은 호출은 자동으로 합쳐진다. href가 같으면 여러 번 불러도 한 번 부른 것과 같다(단 as: "image"는 imageSrcSet·imageSizes까지 같아야 동일 호출로 본다). 그래서 여러 컴포넌트가 같은 리소스를 preload해도 중복 다운로드가 생기지 않는다.

브라우저에서는 렌더 중, Effect, 이벤트 핸들러 등 어디서 불러도 된다. 다만 서버 렌더링이나 서버 컴포넌트에서는 렌더 중(또는 렌더에서 파생된 비동기 맥락)에 부를 때만 동작하고, 그 밖의 호출은 무시된다.

03사용법

곧 필요할 리소스를 렌더 중에 미리 건다. 폰트나 스타일처럼 이후 화면에서 쓸 것이 대표적이다.

import { preload } from 'react-dom'

export function AppRoot() {
  // 곧 쓸 폰트를 미리 내려받는다
  preload('https://example.com/font.woff2', { as: 'font', crossOrigin: 'anonymous' })
  return <Main />
}

반응형 이미지는 imageSrcSet·imageSizes로 실제 로드 규칙에 맞춰 preload한다.

preload('/banner.png', {
  as: 'image',
  imageSrcSet: '/banner512.png 512w, /banner1024.png 1024w',
  imageSizes: '(max-width: 512px) 512px, 1024px',
})

04실무 예시

사용자가 다음 단계로 갈 낌새가 보일 때, 그 화면에 필요한 리소스를 이벤트 핸들러에서 미리 받는 패턴이다. 클릭한 뒤 로딩을 짧게 만든다.

import { preload } from 'react-dom'

export function CallToAction({ startWizard }: { startWizard: () => void }) {
  const onClick = () => {
    // 마법사 화면 스타일을 미리 받아 둔다
    preload('https://example.com/wizardStyles.css', { as: 'style' })
    startWizard()
  }
  return <button onClick={onClick}>시작</button>
}

05왜 중요한가

React 19에서 들어온 리소스 힌트 API 중 하나로, 성능 최적화용이다. 직접 다루지 않아도 앱은 잘 돌아가고, 프레임워크나 라이브러리가 내부에서 알아서 거는 경우가 많다. 특정 리소스의 로드 타이밍을 손으로 당겨야 하는 상황에서만 꺼내 쓰는, 있으면 편한 세밀 조정 도구다.

Reference