3D Editor SDK

The official SDK and CLI for the 3D Component Registry.

📦 Features

• Runtime Library: Securely load and render 3D components with SecureScene.
• CLI Tool: Install components directly into your project with npx editor-sdk.
• Security: Built-in domain locking, signed URL fetching, and local caching.

🛠️ CLI Usage (For Developers)

Use the CLI to install components from the registry into your Next.js project.

1. Login

Authenticate with your registry API key.

npx editor-sdk login

You can specify a custom registry URL:

npx editor-sdk login --host https://your-registry.com

2. Configure Registry URL (Optional)

Set a default registry URL to avoid specifying --host every time.

# View current configuration
npx editor-sdk config

# Set default registry URL
npx editor-sdk config --set-registry https://your-registry.com

# For production
npx editor-sdk config --set-registry https://api.yourdomain.com

Configuration is saved to ~/.3d-editor/config.json.

3. Add Component

Fetch a component by its ID.

npx editor-sdk add <component-id>

Examples:

# Uses configured registry URL
npx editor-sdk add my-scene-123

# Override with --host flag
npx editor-sdk add my-scene-123 --host http://localhost:8080

📚 Library Usage (For Components)

The CLI generates components that use this library under the hood. You typically won't write this code manually, but here is how it works:

import { SecureScene } from 'editor-sdk';

export default function My3DComponent() {
  return (
    <SecureScene 
      id="my-scene-123"
      registryUrl="http://localhost:3000"
    />
  );
}

Props

| Prop | Type | Description | |------|------|-------------| | id | string | The unique ID of the component in the registry. | | registryUrl | string | (Optional) Base URL of the registry. Auto-detected if not provided. | | token | string | (Optional) Auth token for private components. | | onLoad | () => void | Callback when the model finishes loading. | | onError | (err) => void | Callback if loading fails. | | animation | object | (Optional) Override animation settings. | | position | [x, y, z] | (Optional) Override position. | | scale | [x, y, z] | (Optional) Override scale. |

🌐 Registry URL Configuration

The SDK automatically detects the registry URL using the following priority:

1. Explicit prop: <SecureScene registryUrl="..." />
2. Environment variable: NEXT_PUBLIC_REGISTRY_URL
3. Auto-detect localhost: http://localhost:{current-port} (works on any port!)
4. Auto-detect domain: Uses window.location.origin for deployed apps
5. Fallback: http://localhost:3000

Development (Any Port)

The SDK automatically works on any localhost port:

// Works on localhost:3000, localhost:8080, localhost:3001, etc.
<SecureScene id="my-component-123" />

Production (Environment Variable)

Set the registry URL in your environment:

# .env.production
NEXT_PUBLIC_REGISTRY_URL=https://api.yourdomain.com

// Component automatically uses NEXT_PUBLIC_REGISTRY_URL
<SecureScene id="my-component-123" />

Override for Specific Component

<SecureScene 
  id="my-component-123" 
  registryUrl="https://custom-registry.com"
/>

🔧 Troubleshooting

"403 Forbidden"

• Cause: You might be trying to publish a version that already exists.
• Fix: Update the version in package.json.

"Unauthorized"

• Cause: CLI session expired or invalid key.
• Fix: Run npx editor-sdk login again.