Installation

Install

Mirage Engine ships as an ES module with bundled type declarations. three is a peer dependency — install it yourself so your app controls the version.

npm install mirage-engine three

Requirements

Requirement	Version	Note
`three`	`^0.160.0`	Peer dependency, not bundled
Browser	WebGL2 + `MutationObserver` + `IntersectionObserver`	All evergreen browsers
Module format	ESM	The package is `"type": "module"`

⚠️

Mirage touches window, document and WebGLRenderingContext in its constructor. It cannot run during server-side rendering — see SSR frameworks below.

Verify the install

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> injected next to your target

If you see a canvas element logged and your target visually duplicated, the install is working.

SSR frameworks

Import and construct Mirage only on the client.

"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}>{/* your normal markup */}</div>;
}

Sub-packages

mirage-engine already bundles everything you need. The internals are also published separately if you want just one piece:

Package	Use it when
`@mirage-engine/painter`	You want DOM-accurate Three.js materials without the DOM sync
`@mirage-engine/dom-tracker`	You want the batched DOM observer on its own
`@mirage-engine/sandwich`	You want DOM layering above a canvas without Mirage
`@mirage-engine/core`	You are building your own facade over `Engine`

Next steps

Continue to the Quick Start.

What is Mirage Engine?Quick Start