[Rust 공식문서 한국어 정리] 59. Rust wasm-pack 가이드

[Rust 공식문서 한국어 정리] 59. Rust wasm-pack 가이드



원문 제목: wasm-pack — Rust and WebAssembly

작성자: Rust and WebAssembly Working Group



━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📌 1. 서론 — 이 문서가 다루는 내용

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━



이 문서는 wasm-pack을 사용하여 Rust 코드를 WebAssembly로 빌드하고 npm 패키지로 배포하는 방법을 설명합니다.

wasm-pack의 설치, 빌드 명령, 생성된 패키지 구조, 그리고 다양한 빌드 타겟(--target)을 다룹니다.

JavaScript 번들러(webpack, rollup, vite 등)와의 통합, 테스트 실행, 그리고 배포 워크플로우를 중심으로 설명합니다.

Rust로 작성된 고성능 모듈을 웹 프론트엔드에 통합하는 전체 과정을 체계적으로 안내합니다.

Rust 개발자가 웹 생태계에 진입하거나, JS 프로젝트에 Rust 기반 성능 모듈을 통합하려는 경우 필수적입니다.



━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🔑 2. 핵심 개념 4가지

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━



① wasm-pack CLI: Rust 프로젝트를 빌드하고, JS wrapper와 함께 npm 패키지로 패키징하는 도구입니다.

② wasm-bindgen: Rust와 JS 간의 자동 바인딩을 생성하는 매크로와 도구입니다.

③ Build Targets: bundler, web, nodejs, no-modules 등 배포 환경에 따른 출력 형식입니다.

④ pkg/: wasm-pack이 생성하는 출력 디렉토리로, .wasm, .js, .d.ts, package.json을 포함합니다.



━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📖 3. 주요 내용 상세

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━



wasm-pack은 wasm-bindgen과 wasm-opt를 한 번에 실행하여 최적화된 Wasm 모듈을 생성합니다.

cargo install wasm-pack으로 설치하고, 프로젝트 루트에서 wasm-pack build를 실행합니다.

생성된 pkg/ 디렉토리는 즉시 npm publish하거나, 로컬 JS 프로젝트에 링크할 수 있습니다.



빌드 타겟은 --target 옵션으로 지정합니다.

--target bundler는 webpack/rollup/vite 등 ES 모듈 번들러용 출력을 생성합니다.

--target web은 브라우저용 ES 모듈을, --target nodejs는 CommonJS 형태의 Node.js용 패키지를 생성합니다.

--target no-modules는 전역 스크립트로 로드하는 레거시 방식입니다.



wasm-bindgen 매크로는 Rust 함수와 구조체를 JS에 노출합니다.

#[wasm_bindgen]으로 함수나 impl 블록을 표시하면, JS에서 호출 가능한 wrapper가 생성됩니다.

JS 타입(JsValue, js_sys::Date 등)과의 상호작용도 자동으로 처리됩니다.



테스트는 wasm-pack test로 실행합니다.

wasm-pack test --headless --firefox로 브라우저 환경에서 Rust 테스트를 실행할 수 있습니다.

wasm-bindgen-test 크레이트는 Wasm 환경에서의 assert!와 비동기 테스트를 지원합니다.



배포 워크플로우는 GitHub Actions와 연동하여 자동화할 수 있습니다.

태그 푸시 시 wasm-pack build로 패키지를 생성하고, npm publish로 레지스트리에 배포합니다.

Scoped package(@org/name) 배포도 지원하며, monorepo에서 여러 Wasm 패키지를 관리할 수 있습니다.



━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🛠 4. 실전 활용

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━



이미지 처리, 암호화, 물리 시뮬레이션 로직을 Rust로 구현하고 wasm-pack으로 JS에 통합합니다.

--target bundler로 빌드하여 Vite 프로젝트에서 import하여 사용합니다.

wasm-opt로 바이너리 크기를 최적화하고, npm에 배포하여 다른 팀과 공유합니다.



━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ 5. 정리

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━



wasm-pack은 Rust와 WebAssembly 생태계를 연결하는 핵심 도구입니다.

빌드, 바인딩 생성, 테스트, 배포를 하나의 CLI로 통합하여 개발자 경험을 크게 향상시킵니다.

Rust의 성능을 웹에 가져오려면 wasm-pack이 최고의 시작점입니다.



━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🔗 출처 링크

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━



원문: https://rustwasm.github.io/wasm-pack/

wasm-pack GitHub: https://github.com/rustwasm/wasm-pack



#Rust #WasmPack #WebAssembly #JavaScript #npm #Frontend #번역