PortalGL

Put Three.js content into your HTML layout and keep it aligned as the page scrolls. PortalGL handles DOM tracking, canvas positioning, object projection, and clipping while you own the scenes, assets, renderer, and animation loop.

pnpm add portalgl three

Start with a complete rotating-card example.

• Views and 3D objects
• Image planes
• Post-processing
• Tracking and custom rendering
• API reference

Imports

| Import | Use it for | | --- | --- | | portalgl or portalgl/track | Renderer-independent tracking and canvas coordination | | portalgl/three | ThreeDOM, ThreeProjector, and the tracking API |

PortalGL manages element measurements automatically. Three.js r184+ is an optional peer needed for the Three.js integration. Core does not load React or Three.js. ESM, CommonJS, and TypeScript are supported; construct controllers in the browser.

Moving from xyz

Replace @joycostudio/xyz/track with portalgl (or portalgl/track), and import tracking-related Three.js APIs from portalgl/three. Move all tracking imports together. Measurement setup and cleanup are automatic. Warmup, state primitives, and debug tools remain in xyz.

The engine was extracted from xyz commit 684e302c39dc8095cad2d429db9d19486f026067. PortalGL has no runtime dependency on xyz; its dev dependency tests Warmup interoperability. Removing tracking from xyz is a separate follow-up.

Development

pnpm install
pnpm dev             # Library watcher + Next.js docs (default port 3000)
pnpm docs:build      # Production build of library and docs
pnpm typecheck
pnpm test
pnpm exec playwright install chromium
pnpm test:track      # Browser regressions, including WebGPU and WebGL2

The app in apps/docs reads docs/ directly. pnpm docs also starts both watchers; pnpm dev:workspace watches only the library. See browser test requirements and the automatic Changesets release flow.