React에서 WASM 모듈 로드하기

브라우저 표준 방식으로 WASM 모듈을 로드하는 방법은 WebAssembly.instantiateStreaming(fetch(url), importObject)입니다. 이 방식은 WASM 바이너리를 다운로드하는 동시에 스트리밍하고, 즉시 컴파일을 시작하며, 모듈과 인스턴스를 포함한 객체로 이행됩니다. 프로덕션에서 사용하기에 가장 효율적인 로드 방법입니다.

비트와 웹팩 같은 번들러는 동적 가져오기 구문을 사용해 WASM 파일을 ES 모듈로 가져오는 것을 지원합니다: import('./module.wasm'). 번들러가 로드 메커니즘을 처리합니다. 이 방식은 코드 분할과 자연스럽게 통합됩니다. 가져오는 코드가 실행될 때만 WASM 모듈이 로드됩니다.

WASM 모듈 로드는 비동기 작업이므로 useEffect 훅 안에서 수행해야 합니다. 효과 내부에서 모듈을 가져와 인스턴스화하고, 내보낸 함수를 상태나 참조에 저장한 다음 초기화가 완료되면 컴포넌트를 업데이트하십시오. 빈 종속성 배열은 컴포넌트가 마운트될 때마다 모듈이 한 번만 로드되도록 합니다.

초기화할 때 다시 렌더링되는 것을 방지하려면 WASM 인스턴스를 useRef에 저장하고, 애플리케이션 전체에서 공유하는 싱글턴이라면 모듈 수준 변수에 저장하십시오. useState에 저장해도 작동하지만 인스턴스를 사용할 수 있게 될 때 추가로 다시 렌더링됩니다. 단순한 경우에는 이 방법도 허용할 수 있습니다.

기능에 WASM 모듈이 필요한 컴포넌트의 경우 컴포넌트를 React.lazy로 감싸고 Suspense 경계 안에서 렌더링하십시오. 동적 가져오기의 일부로 WASM 모듈을 로드할 수 있습니다. 모듈이 초기화되는 동안 Suspense가 대체 스켈레톤을 표시하여 깔끔한 로딩 경험을 제공합니다.

WASM 모듈은 일반적인 연결 환경에서 모듈 크기와 기기 속도에 따라 로드하고 인스턴스화하는 데 100~500ms가 걸립니다. 초기화가 진행되는 동안에는 항상 로딩 표시기(스켈레톤, 스피너 또는 진행률 표시줄)를 표시하십시오. 시각적 피드백 없이 WASM 초기화 때문에 사용자 인터페이스를 차단하면 멈춘 것처럼 느껴집니다.

인스턴스화가 끝나면 WASM 함수는 instance.exports.myFunction()을 통해 사용할 수 있습니다. wasm 바인드젠(러스트 도구 모음)을 사용하는 경우, 생성된 JavaScript 연결 모듈이 적절한 형 변환을 적용해 함수를 직접 내보냅니다. 러스트 소스에 정의된 형식을 사용해 일반 JavaScript 함수처럼 호출합니다.

동기 함수 호출과 마찬가지로 리액트 이벤트 처리기에서 WASM 함수를 호출하십시오: function handleClick() { const result = wasmInstance.current.processImage(imageData); setResult(result); }. WASM 함수 호출은 동기식이며 계산이 완료될 때까지 호출 스레드를 차단합니다. 장시간 작업을 수행할 때 워커에서 실행해야 하는 또 다른 이유입니다.

WASM 초기화는 실패할 수 있습니다. 가져오기에 실패하거나, 모듈이 호환되지 않거나, 브라우저에 필요한 기능이 없을 수 있습니다. WASM 종속 컴포넌트를 리액트 오류 경계로 감싸 초기화 실패를 포착하고 대체 화면을 표시하십시오. 디버깅을 위해 오류를 기록하고 가능하면 우아한 성능 저하 경로를 제공하십시오.

WASM 모듈을 올바르게 처리하려면 비트에 두 플러그인이 필요합니다. vite-plugin-wasm은 WASM 파일 가져오기를 처리하고, vite-plugin-top-level-await는 일부 WASM 연결 코드에서 사용하는 최상위 대기 구문을 활성화합니다. 두 플러그인을 설치하고 vite.config.ts의 plugins 배열에 추가하십시오.

웹팩 프로젝트에서는 webpack.config.js에서 asyncWebAssembly 실험 기능을 활성화하십시오: experiments: { asyncWebAssembly: true }. 이렇게 하면 브라우저가 WASM 파일을 비동기적으로 로드하는 방식으로 import()을 사용할 수 있습니다. 크리에이트 리액트 앱 프로젝트에서는 이 구성을 추가하려면 프로젝트 설정을 추출하거나 CRACO를 사용해야 합니다.

WebAssembly.instantiate()보다 WebAssembly.instantiateStreaming()을 사용할 때의 장점은 무엇인가요?

WebAssembly.instantiateStreaming(fetch(url)) 또는 useEffect에서 동적 가져오기를 사용해 WASM을 로드하십시오. 인스턴스는 useRef 또는 모듈 싱글턴에 저장하십시오. 100~500ms 동안 진행되는 초기화 중에는 로딩 상태를 표시하십시오. instance.exports.fn()을 통해 내보내기 항목에 접근하십시오. 초기화 실패에는 오류 경계를 사용하십시오. 비트는 vite-plugin-wasm과 vite-plugin-top-level-await로 구성하십시오.