unicornstudio-react

unicornstudio-react is a community-maintained wrapper that brings Unicorn.Studio’s WebGL scene engine into React and Next.js applications as a single drop-in component. Rather than hand-rolling script injection and imperative scene setup, developers render <UnicornScene projectId="..." /> (or the Next.js-optimized unicornstudio-react/next import) and get lazy loading, resize handling, WebGL-support detection, and cleanup for free.

The package ships two entry points — a framework-agnostic React build and a "use client" Next.js build that uses next/image for placeholders — both backed by a shared useUnicornScene hook that owns the scene’s full lifecycle: initialization against window.UnicornStudio.addScene, timeout handling, resize observation, pause/resume syncing, and teardown on unmount. As of v2.2 it also supports Unicorn Studio’s authored variables and presets (scene-level parameters like brand colors or theme groups), applying them declaratively via props and syncing changes to a live scene without re-initializing it.

By default the package bundles Unicorn Studio’s SDK and three.js-based model-renderer extension directly (loaded via blob URLs and an import map), so consumers don’t need to add an external <script> tag or worry about CDN availability; an sdkUrl prop remains available for anyone who wants to point at a custom-hosted SDK build instead.

What You Get

• A single <UnicornScene> component for React (Vite/CRA) and a parallel unicornstudio-react/next build for Next.js with "use client" and next/image placeholder support
• Full TypeScript definitions for scene props, the UnicornStudioScene runtime API, and variable/preset types
• Bundled Unicorn Studio SDK and three.js model-renderer extension loaded via blob URLs by default, so no external <script> tag or CDN dependency is required
• Declarative support for authored scene variables and presets, applied on load via initialVariables/initialPreset and synced live via setVariables()/setPreset() without re-initializing the scene
• Built-in lazy loading, WebGL-support detection, ResizeObserver-driven scene resizing, and configurable placeholder content (image, CSS class, or custom React node) for loading/error states
• A sceneRef escape hatch exposing the full imperative scene API (getLayers, setProp, setTexture, getVariableManifest, onVariableChange, getMouse, etc.) for advanced control

Common Use Cases

• Dropping an interactive WebGL hero background or section animation into a Next.js marketing site without writing script-loading boilerplate
• Theming a shared scene per page or per user preference by switching an authored preset (e.g. light/dark) through the preset prop
• Driving scene parameters (brand colors, effect intensity) from app state or a CMS via the variables prop instead of hardcoding them in the Unicorn Studio editor
• Building custom animated controls on top of a scene (e.g. GSAP-driven variable tweening) using the sceneRef imperative API
• Self-hosting scene JSON files instead of Unicorn Studio’s hosted projects, via the jsonFilePath prop

Under The Hood

Architecture The package separates a framework-agnostic core from two thin framework-specific shells: src/react/ and src/next/ each export a component and a useUnicornStudioScript hook, but both delegate scene lifecycle to the shared useUnicornScene hook in src/shared/hooks.ts. That hook manages initialization against window.UnicornStudio.addScene, using a serialized config key to avoid redundant re-initialization, refs (not state) for callbacks/variables/preset so they don’t retrigger the init effect, a withTimeout wrapper guarding against a hung SDK call, and a replaySceneDrift mechanism that re-applies prop changes which occurred while addScene() was still in flight — a subtle correctness detail for a library built around an async third-party script. Script loading itself is isolated in src/shared/sdk-loader.ts, which de-duplicates concurrent load requests via a promise cache and supports both an externally hosted SDK URL and the package’s bundled SDK (injected as an inline script plus a blob-URL import map for the three.js model-renderer extension).

Tech Stack Written in TypeScript and built with tsup into dual ESM/CJS output across two entry points (index and next), with react/react-dom as peer dependencies (>=18) and next as an optional peer. The bundled Unicorn Studio SDK and three.js extension files are generated from a vendor/unicornstudio/ source tree via a sync-sdk script (scripts/generate-sdk-bundle.mjs) rather than fetched at runtime. Testing uses Vitest with @testing-library/react and jsdom; linting is ESLint (typescript-eslint, eslint-plugin-react/react-hooks) plus Prettier, wired into a prepublishOnly script that runs lint, type-check, and build before every publish, backed by a GitHub Actions workflow and a SonarCloud quality gate badge.

Code Quality The test suite is extensive relative to the package’s size — nine test files covering the shared hook (useUnicornScene.test.ts alone runs to nearly 900 lines), the SDK loader, utils, constants, and both the React and Next.js components. Error handling is deliberate rather than an afterthought: a sanitizeErrorMessage helper redacts URLs and file paths from thrown errors before they reach onError callbacks or user-visible error UI, and parameter validation (validateScale/validateFPS) runs before any scene is created. Naming is consistent and every exported function and type carries TSDoc comments with @remarks and @example blocks.

API Design The public surface is small and consistent: one component, one set of props, and an optional sceneRef for advanced access, so getting a scene on screen requires zero boilerplate beyond a projectId. Sensible defaults (lazy loading on, 60fps, 1.5x DPI) mean most consumers never touch the tuning props, while the variables/presets API and full typed UnicornStudioScene interface give power users direct access to the same runtime the Unicorn Studio editor exposes, without the wrapper hiding capability behind an incomplete abstraction.