설치

설치하기

Mirage Engine은 타입 선언이 포함된 ES 모듈로 배포됩니다. three는 peer dependency이므로 버전은 여러분 앱에서 직접 정합니다.

npm install mirage-engine three

요구 사항

항목	버전	비고
`three`	`^0.160.0`	peer dependency, 번들에 포함되지 않음
브라우저	WebGL2 + `MutationObserver` + `IntersectionObserver`	모든 최신 브라우저
모듈 형식	ESM	패키지가 `"type": "module"`

⚠️

Mirage는 생성자에서 window, document, WebGLRenderingContext를 건드립니다. 서버 사이드 렌더링 중에는 실행할 수 없습니다 — 아래 SSR 프레임워크를 참고하세요.

설치 확인

import { Mirage } from "mirage-engine";
 
const target = document.querySelector("#target") as HTMLElement;
const mirage = new Mirage(target, {});
 
await mirage.start();
console.log(mirage.getCanvas()); // 타깃 옆에 삽입된 <canvas>

캔버스 요소가 로그에 찍히고 타깃이 시각적으로 복제되어 보이면 정상입니다.

SSR 프레임워크

Mirage는 클라이언트에서만 import하고 생성하세요.

"use client";
import { useEffect, useRef } from "react";
 
export function MirageLayer() {
  const ref = useRef<HTMLDivElement>(null);
 
  useEffect(() => {
    if (!ref.current) return;
    let mirage: import("mirage-engine").Mirage | undefined;
 
    (async () => {
      const { Mirage } = await import("mirage-engine");
      mirage = new Mirage(ref.current!, { mode: "overlay" });
      await mirage.start();
    })();
 
    return () => mirage?.destroy();
  }, []);
 
  return <div ref={ref}>{/* 평소대로 쓰는 마크업 */}</div>;
}

서브 패키지

mirage-engine 하나면 필요한 건 다 들어 있습니다. 내부 모듈만 따로 쓰고 싶다면 개별 패키지도 배포되어 있습니다.

패키지	이럴 때 사용
`@mirage-engine/painter`	DOM 동기화 없이 DOM 스타일 그대로의 Three.js 머티리얼만 필요할 때
`@mirage-engine/dom-tracker`	배치 처리되는 DOM 옵저버만 필요할 때
`@mirage-engine/sandwich`	Mirage 없이 캔버스 위에 DOM을 레이어링하고 싶을 때
`@mirage-engine/core`	`Engine` 위에 자체 파사드를 만들 때

다음 단계

빠른 시작으로 이어집니다.

Mirage Engine이란?빠른 시작