토파즈는 다양한 제품군에서 WebAssembly를 사용합니다. 제품마다 소유권과 신뢰 경계가 다릅니다. 빌드 명령을 선택하기 전에 어떤 제품을 만들지 먼저 정하세요.
1. 플레이그라운드: 첫 브라우저 실험
CLI를 설치하지 않고 소형 토파즈 프로그램을 수정·검사·실행하려면 사이트 플레이그라운드를 사용하세요. 브라우저는 Worker 내부로 컴파일러와 인터프리터 WebAssembly를 로드합니다. 이 방식은 소스 코드를 대화형으로 실험하는 용도로만 유효합니다. 애플리케이션이 배포되거나 브라우저 리소스에 제한 없이 접근할 수 있음을 의미하지는 않습니다.
설치한 CLI로 동일한 실험을 진행하려면 첫 프로그램에서 시작하세요.
2. Raw Web: 기존 호스트가 토파즈 호출
기존 JavaScript ES 모듈 호스트가 UI를 제어하고 지정한 토파즈 내보내기 함수를 호출하는 구조라면 Raw Web을 선택하세요.
topaz build --target web main.tpz --release --out-dir web-product아티팩트에는 topaz-web.js, topaz-web.d.ts, topaz-web.wasm 및 공통 아티팩트 파일이 포함됩니다. 생성된 모듈에서 instantiateTopaz를 가져오세요. 디렉터리는 HTTP로 제공합니다. 호스트는 생성된 타입 ABI를 그대로 준수해야 합니다.
3. Worker: 같은 ABI를 메인 스레드 밖에서 사용
기존 호스트에 요청과 응답을 주고받는 통신 계층이 추가로 필요하다면 Worker를 선택하세요. 이 계층은 Raw Web 제품을 감싸는 형태로 함께 생성됩니다.
topaz build main.tpz --target web-worker --release --out-dir worker-product아티팩트에 topaz-web-worker.js와 topaz-web-worker-client.js가 추가됩니다. Worker는 UI를 생성하지 않으며 권한을 확장하지도 않습니다. UI와 권한 소유권은 계속 JavaScript 호스트가 가집니다.
4. 관리형 Web 애플리케이션: 토파즈가 UI 소유
모델, 메시지, 상태 갱신, 화면, 선언한 브라우저 권한까지 토파즈가 전적으로 소유하는 구조라면 web-app을 선택하세요.
topaz init --target web-app --root hello-web
topaz lock --root hello-web
topaz check --root hello-web --locked
topaz test hello-web/tests/app.tpz --root hello-web --locked
topaz dev --root hello-web --port 8000
topaz build --root hello-web --locked --release --out-dir web-app-product이 타겟은 패키지에서만 사용할 수 있습니다. 독립적인 정적 제품 하나를 생성하며, 그 내부에는 index.html, 검사된 topaz-app.js 호스트, Raw Web 파일, 권한 메타데이터, 선언한 스타일과 에셋이 포함됩니다. topaz dev는 루프백 인터페이스에서만 동작하며, 프로덕션 서버용이 아닙니다.
필수 조건과 복구
Raw Web, Worker, 관리형 Web 빌드에는 Rust가 필요합니다. 해당 Rust 환경에는 wasm32-unknown-unknown 타겟이 설치되어 있어야 합니다. 완성된 브라우저 제품에는 토파즈 CLI나 Rust가 필요하지 않으므로 HTTP로 제공하세요. file:// 프로토콜에서 ES 모듈과 WASM을 직접 로드하는 방식은 지원하는 경로가 아닙니다.
호스트와 런타임 식별자가 일치하지 않는다는 안내가 브라우저에 표시되면 기존 JavaScript와 새 WASM을 혼용하지 마세요. 단일 빌드로 생성된 디렉터리 전체를 함께 배포합니다. 관리형 출력 디렉터리가 변경되었다면 기존 디렉터리를 보존하고 비어 있는 새 디렉터리에 빌드하세요.