Registry / web-framework / unicornstudio-react

unicornstudio-react

library2.1.4-1jsnpmunverified

The `unicornstudio-react` package provides a community-created React component for embedding interactive 3D scenes designed with Unicorn.Studio into web applications. Currently at version `2.1.4-1`, this library sees frequent updates, often involving bumps to the underlying Unicorn.Studio SDK and fixes for compatibility issues in modern React and Next.js environments. Key differentiators include full TypeScript support, an optimized import path specifically for Next.js applications (leveraging Next.js `Script` and `Image` components), performance optimizations like lazy loading, responsive design, and comprehensive error handling. It allows embedding scenes using either a project ID from Unicorn.Studio's cloud service or a local JSON file. It's important to note that this package is not officially affiliated with Unicorn.Studio and relies on their proprietary script and services.

web-framework

npm install unicornstudio-react

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · UNICORNSTUDIO-REAC

unicornstudio-react

web-frameworkjavascriptv2.1.4-1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

UnicornScene

✓ import UnicornScene from 'unicornstudio-react';

✗ const UnicornScene = require('unicornstudio-react');

This is the default export path for standard React environments (e.g., Vite, Create React App). It uses standard HTML `<script>` and `<img>` tags for integration.

UnicornScene (Next.js optimized)

✓ import UnicornScene from 'unicornstudio-react/next';

✗ import UnicornScene from 'unicornstudio-react';

For Next.js applications, use this specific import path. It leverages Next.js `Script` and `Image` components for enhanced performance, optimization, and SSR-safety.

UnicornSceneProps (Type)

✓ import type { UnicornSceneProps } from 'unicornstudio-react';

The package ships with full TypeScript types. Import `UnicornSceneProps` for type-checking the component's properties, useful for advanced configurations or custom wrappers.

This quickstart demonstrates embedding a Unicorn.Studio interactive scene using the Next.js optimized component, including loading and error handling. It fetches a project ID from environment variables and sets various display properties.

import { useState } from 'react'; import UnicornScene from 'unicornstudio-react/next'; export default function InteractiveScenePage() { const [isSceneLoaded, setIsSceneLoaded] = useState(false); const [error, setError] = useState<Error | null>(null); const handleLoad = () => { console.log('Unicorn.Studio scene loaded successfully!'); setIsSceneLoaded(true); }; const handleError = (err: Error) => { console.error('Failed to load Unicorn.Studio scene:', err); setError(err); }; // Replace 'YOUR_PROJECT_EMBED_ID' with your actual project ID from Unicorn.Studio // or use jsonFilePath="/path/to/your/scene.json" const projectId = process.env.NEXT_PUBLIC_UNICORN_STUDIO_PROJECT_ID ?? 'YOUR_PROJECT_EMBED_ID'; return ( <div style={{ width: '100vw', height: '100vh', display: 'flex', justifyContent: 'center', alignItems: 'center', background: '#f0f0f0' }}> {!isSceneLoaded && !error && <p>Loading interactive scene...</p>} {error && <p style={{ color: 'red' }}>Error loading scene: {error.message}</p>} <UnicornScene projectId={projectId} width="100%" height="100%" scale={0.8} dpi={2} lazyLoad={true} altText="An interactive 3D scene from Unicorn.Studio" onLoad={handleLoad} onError={handleError} style={{ border: '1px solid #ccc', borderRadius: '8px' }} /> </div> ); }

Debug

Known issues

gotchaThis package is a community-created wrapper and is not officially affiliated with Unicorn.Studio. Its operation depends on Unicorn.Studio's proprietary script and services, which are external to this package's control.

fix

Understand the external dependencies; ensure Unicorn.Studio services are operational and your project ID or JSON file path is correct. Check Unicorn.Studio's official documentation for service status.

affects: *

breakingSDK version bumps can introduce breaking changes in the underlying Unicorn.Studio runtime. For instance, the transition to SDK v2.1.0 included a breaking change for flattened scenes if not updated.

fix

Always review the Unicorn.Studio SDK changelog and `unicornstudio-react` release notes before upgrading major versions of the SDK. Test thoroughly after any updates.

affects: >=2.0.0

gotchaPrior to version `2.1.4-1`, users in Next.js App Router environments, especially with React Strict Mode enabled, might experience issues such as duplicate canvas rendering or multiple script initializations. This was due to specific handling of script loading and component mounting.

fix

Upgrade to `unicornstudio-react@2.1.4-1` or higher. Always use the Next.js-optimized import path: `import UnicornScene from 'unicornstudio-react/next';` to benefit from specific optimizations and bug fixes.

affects: <2.1.4-1

gotchaUsing the default import `import UnicornScene from 'unicornstudio-react';` in a Next.js project will bypass the performance optimizations and specialized handling provided by the Next.js-optimized path. This can lead to less efficient script loading and image handling, impacting Lighthouse scores and overall performance.

fix

For all Next.js projects, consistently use `import UnicornScene from 'unicornstudio-react/next';` to ensure optimal performance and compatibility.

affects: *

Errors

Common errors & fixes

Warning: Encountered two children with the same key, `__reactFiber$ID`...

React Strict Mode causing re-renders that lead to duplicate canvas elements, often seen in Next.js environments with older versions of the component.

fix

Update to `unicornstudio-react@2.1.4-1` or newer. Ensure React Strict Mode is compatible or consider adjusting component keys if custom rendering logic is involved.

Unicorn.Studio scene does not load, or a blank canvas is displayed in the browser.

Incorrect `projectId` or `jsonFilePath`, network issues preventing the external Unicorn.Studio script from loading, or content security policy (CSP) blocking external scripts from Unicorn.Studio's CDN.

fix

Verify that your `projectId` is correctly copied from Unicorn.Studio or that `jsonFilePath` points to an accessible JSON file. Check the browser console for network errors, JavaScript errors, or CSP violations. Ensure `https://cdn.jsdelivr.net` and `https://assets.unicorn.studio` are allowed in your CSP.

Module not found: Can't resolve 'unicornstudio-react/next'

Typo in the import path, or the `unicornstudio-react` package is not correctly installed or its `exports` map is not being properly resolved by your bundler.

fix

Check for typos in `import UnicornScene from 'unicornstudio-react/next';`. Ensure `npm install unicornstudio-react` or `yarn add unicornstudio-react` was run successfully. If using an older bundler, ensure it supports the `exports` field in `package.json`.

ReferenceError: UnicornStudio is not defined (or similar error related to the global UnicornStudio object)

The Unicorn.Studio external script failed to load, was blocked, or took too long to load, and the component attempted to initialize before the global `UnicornStudio` object was available.

fix

Ensure external script loading is not blocked by a Content Security Policy (CSP). Check network requests in developer tools to confirm the script (`unicornStudio.umd.js`) is loading. The component handles script loading automatically, but external factors can interfere. Consider using the `onLoad` prop to ensure readiness if manually interacting with the SDK or deferring related logic.

Upgrade

Version history

2.1.4-1latest on npm

Audit

Dependencies

reactrequiredPeer dependency for React component functionality.

react-domrequiredPeer dependency for React component functionality.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/diegopeixoto/unicornstudio-react ↗

packagehttps://www.npmjs.com/package/unicornstudio-react ↗

homepagehttps://unicorn.studio ↗