preinit

01무엇

preinit는 스타일시트나 외부 스크립트를 미리 내려받고, 다 받으면 곧바로 적용·실행하는 API다. 다운로드에서 멈추는 preload와 달리 실행·삽입까지 간다.

인자는 리소스 URL인 href와 옵션 객체다. as는 필수이고 "script" 또는 "style"이다.

import { preinit } from 'react-dom'

preinit('https://example.com/script.js', { as: 'script' })

스타일시트에는 precedence가 필수다("reset", "low", "medium", "high" — 삽입 순서·우선순위). 그 밖에 crossOrigin, integrity, nonce, fetchPriority가 선택이다. 반환값은 없다.

02무슨 일이 일어나나

preinit로 건 스크립트는 다운로드가 끝나면 실행되고, 스타일시트는 문서에 삽입돼 즉시 적용된다. 이 점이 preload와 갈린다. preload는 내려받기만 하고, preinit는 받아서 곧장 쓰는 상태로 만든다. 스타일을 바로 먹이거나 스크립트를 즉시 돌려야 하면 preinit, 다운로드만 앞당기면 preload다.

같은 href로 여러 번 불러도 한 번 부른 것과 같은 효과다. 브라우저에서는 렌더 중, Effect, 이벤트 핸들러 등 어디서 불러도 되지만, 서버 렌더링에서는 렌더 중(또는 렌더에서 파생된 비동기 맥락)의 호출만 동작하고 나머지는 무시된다.

스타일시트의 precedence는 여러 스타일 사이의 삽입 순서를 정한다. 높은 값이 낮은 값을 덮을 수 있어, 스타일 적용 순서를 통제하는 손잡이가 된다.

03사용법

곧 실행·적용할 스크립트나 스타일을 렌더 중에 미리 건다. 스타일에는 precedence를 함께 준다.

import { preinit } from 'react-dom'

export function AppRoot() {
  // 받는 즉시 실행할 외부 스크립트
  preinit('https://example.com/script.js', { as: 'script' })
  // 받는 즉시 적용할 스타일 — 순서는 precedence로
  preinit('https://example.com/style.css', { as: 'style', precedence: 'medium' })
  return <Main />
}

04실무 예시

다음 화면으로 넘어가기 직전, 그 화면의 스타일을 미리 받아 적용해 두는 패턴이다. 전환 뒤 스타일이 뒤늦게 먹으며 화면이 튀는 것을 줄인다.

import { preinit } from 'react-dom'

export function StartWizard({ startWizard }: { startWizard: () => void }) {
  const onClick = () => {
    // 마법사 화면 스타일을 미리 받아 곧바로 적용
    preinit('https://example.com/wizardStyles.css', { as: 'style', precedence: 'high' })
    startWizard()
  }
  return <button onClick={onClick}>시작</button>
}

05왜 중요한가

React 19의 리소스 힌트 API 중 하나로, 성능 최적화용이다. 직접 쓰지 않아도 앱은 돌아가고, 보통은 프레임워크나 라이브러리가 내부에서 다룬다. 특정 스크립트·스타일의 로드와 적용 시점을 손으로 당겨야 할 때만 꺼내는 세밀 조정 도구다.

Reference