preinitModule

📝 참고

React 기반 프레임워크는 대부분 리소스 로딩을 자동으로 처리해주기 때문에, 이 API를 직접 호출할 필요가 없을 수도 있어요. 자세한 내용은 프레임워크 문서를 참고하세요.

소개

preinitModule을 사용하면 ESM 모듈을 미리 가져와서 평가(evaluate)할 수 있어요.

preinitModule("https://example.com/module.js", {as: "script"});

---

레퍼런스

preinitModule(href, options)

ESM 모듈을 프리이닛(preinit)하려면, react-dom에서 preinitModule 함수를 호출하세요.

import { preinitModule } from 'react-dom';

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

아래에서 더 많은 예제를 확인하세요.

preinitModule 함수는 브라우저에게 주어진 모듈의 다운로드와 실행을 시작해야 한다는 힌트를 제공해서, 시간을 절약할 수 있어요. preinit한 모듈은 다운로드가 완료되면 실행돼요.

💡 부연 설명: "preinit"은 "pre-initialize(미리 초기화)"의 줄임말이에요. 일반적으로 모듈은 코드에서 import문을 만나거나 동적으로 import()를 호출할 때 다운로드되고 실행되는데, preinitModule을 사용하면 그 시점보다 훨씬 일찍 다운로드와 실행을 시작할 수 있어요.

ESM(ECMAScript Module)은 import/export 문법을 사용하는 최신 JavaScript 모듈 시스템이에요. <script type="module"> 형태로 로드되는 모듈을 말해요.

매개변수(Parameters)

• href: 문자열이에요. 다운로드하고 실행하려는 모듈의 URL이에요.
• options: 객체예요. 다음 프로퍼티들을 포함해요:
  • as: 필수 문자열이에요. 반드시 'script'여야 해요.
  • crossOrigin: 문자열이에요. 사용할 CORS 정책이에요. 가능한 값은 anonymous와 use-credentials예요.
  • integrity: 문자열이에요. 진위성을 확인하기 위한 모듈의 암호화 해시예요.
  • nonce: 문자열이에요. 엄격한 Content Security Policy를 사용할 때 모듈을 허용하기 위한 암호화 nonce예요.

반환값(Returns)

preinitModule은 아무것도 반환하지 않아요.

주의사항(Caveats)

• 같은 href로 preinitModule을 여러 번 호출하는 것은 한 번 호출하는 것과 같은 효과를 가져요.
• 브라우저에서는 어떤 상황에서든 preinitModule을 호출할 수 있어요: 컴포넌트를 렌더링하는 동안, Effect 안에서, 이벤트 핸들러 안에서 등등.
• 서버 사이드 렌더링이나 Server Components를 렌더링할 때, preinitModule은 컴포넌트를 렌더링하는 동안 호출하거나 컴포넌트 렌더링에서 시작된 비동기 컨텍스트에서 호출할 때만 효과가 있어요. 그 외의 모든 호출은 무시돼요.

---

사용법

렌더링할 때 프리로드하기

컴포넌트나 그 자식들이 특정 모듈을 사용할 것을 알고 있고, 모듈이 다운로드되는 즉시 평가되어 효과를 발휘하는 것이 괜찮다면, 컴포넌트를 렌더링할 때 preinitModule을 호출하세요.

import { preinitModule } from 'react-dom';

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

브라우저가 모듈을 다운로드하되 즉시 실행하지 않길 원한다면, 대신 preloadModule을 사용하세요. ESM 모듈이 아닌 스크립트를 프리이닛하고 싶다면, preinit을 사용하세요.

💡 부연 설명:

• preinitModule: ESM 모듈을 다운로드하고 즉시 실행해요
• preloadModule: ESM 모듈을 다운로드만 하고 실행은 나중으로 미뤄요
• preinit: 일반 스크립트(ESM이 아닌)를 다운로드하고 즉시 실행해요

언제 어떤 걸 쓰냐면:

• 모듈이 즉시 실행되어도 괜찮고(부작용이 없거나 즉시 필요한 경우) → preinitModule
• 모듈을 미리 다운로드만 하고 실제 사용 시점에 실행하고 싶을 때 → preloadModule

예를 들어, 애널리틱스 모듈 같은 건 페이지가 로드되자마자 실행되어야 하니까 preinitModule이 좋고, 사용자가 특정 버튼을 클릭했을 때만 필요한 모듈이라면 preloadModule로 미리 다운로드만 해두는 게 좋아요.

이벤트 핸들러에서 프리로드하기

모듈이 필요한 페이지나 상태로 전환하기 전에 이벤트 핸들러에서 preinitModule을 호출하세요. 이렇게 하면 새 페이지나 상태를 렌더링하는 동안 호출하는 것보다 프로세스를 더 일찍 시작할 수 있어요.

import { preinitModule } from 'react-dom';

function CallToAction() {
  const onClick = () => {
    preinitModule("https://example.com/module.js", {as: "script"});
    startWizard();
  }
  return (
    <button onClick={onClick}>Start Wizard</button>
  );
}

💡 부연 설명: 사용자가 "Start Wizard" 버튼을 클릭하면 마법사 화면으로 이동하는데, 그 화면에서 특정 모듈이 필요하다는 걸 알고 있다면, 버튼 클릭 즉시 preinitModule을 호출하는 게 좋아요.

버튼 클릭 → preinitModule 호출 → 모듈 다운로드 시작 → startWizard() 실행 → 마법사 화면 렌더링

이런 순서로 진행되면서 모듈 다운로드가 백그라운드에서 진행되고, 마법사 화면이 실제로 그 모듈을 사용할 때쯤이면 이미 다운로드가 완료되어 있을 가능성이 높아져요. 결과적으로 사용자가 기다리는 시간이 줄어들죠!

만약 마법사 컴포넌트가 렌더링될 때 preinitModule을 호출하면, 이미 화면 전환이 시작된 후에 모듈 다운로드가 시작되니까 사용자가 더 오래 기다려야 할 수 있어요. 그래서 이벤트 핸들러에서 미리 호출하는 게 더 효과적이에요!