Unicorn.Studio React Component

2.1.4-1 verified Sat Apr 25 auth: no javascript

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.

Common errors

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

cause 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.

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

cause 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.

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

cause 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.

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

cause 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.

Warnings

gotcha This 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.

breaking SDK 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.

gotcha Prior 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.

gotcha Using 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.

Install

npm install unicornstudio-react

yarn add unicornstudio-react

pnpm add unicornstudio-react

Imports

UnicornScene
wrong
```
const UnicornScene = require('unicornstudio-react');
```
correct
```
import UnicornScene from '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)
wrong
```
import UnicornScene from 'unicornstudio-react';
```
correct
```
import UnicornScene from 'unicornstudio-react/next';
```
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.

Quickstart

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>
  );
}