helios studio

Launch the Helios Studio visual editor

The studio command starts a local development server with the Helios Studio visual editor interface.

Usage

helios studio [options]

Options

--port · number · default: "5173"

Port to listen on. Short form: -p.

What is Studio?

Helios Studio is a visual development environment that provides:

• Real-time preview of your compositions
• Component browser with live search
• One-click installation of components from the registry
• Timeline editor for animation timing
• Property inspector for component configuration
• Hot module replacement for instant updates

Prerequisites

Before running Studio, ensure you have:

1. A Helios project initialized with helios init
2. Dependencies installed with npm install
3. A helios.config.json file in your project root

Examples

Start Studio with default port

helios studio

Output:

Starting Studio...
Fetching component registry (react)...
Studio Root: /node_modules/@helios-project/studio

  VITE v5.0.0  ready in 500 ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: http://192.168.1.100:5173/

Use a custom port

helios studio --port 3000

Starts Studio on port 3000 instead of the default 5173.

Start Studio and open in browser

helios studio && open http://localhost:5173

Studio features

Component installation

Studio provides a visual component browser:

1. Click the “Components” tab
2. Search or browse available components
3. Click “Install” to add to your project
4. Components are automatically configured for your framework

Live preview

Studio renders your composition in real-time:

• Changes to your code update instantly
• Timeline scrubbing for frame-by-frame inspection
• Playback controls (play, pause, loop)
• Export directly from the preview

Component management

Manage installed components:

• Update components to the latest version
• Remove components you no longer need
• View component source code
• Check for available updates

Configuration

Studio reads your helios.config.json to:

• Determine your framework (React, Vue, Svelte, etc.)
• Filter components compatible with your framework
• Configure component installation directories
• Connect to custom component registries

Example configuration

{
  "version": "1.0.0",
  "framework": "react",
  "registry": "https://registry.helios-project.dev",
  "directories": {
    "components": "src/components/helios",
    "lib": "src/lib"
  },
  "components": ["fade-in", "slide-in"],
  "dependencies": {}
}

Integration with Vite

Studio uses Vite under the hood and respects your vite.config.js:

• Framework plugins (React, Vue, Svelte) are automatically loaded
• Path aliases are respected
• Custom Vite plugins work seamlessly

Example Vite config

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      '@': '/src',
    },
  },
});

Studio automatically uses this configuration.

Skills integration

Studio includes bundled skills for AI-assisted development:

• Component generation
• Animation suggestions
• Code completion
• Error diagnosis

Skills are automatically detected from the CLI package.

Troubleshooting

Port already in use

If port 5173 is already in use:

helios studio --port 5174

Or Studio will automatically find the next available port:

Port 5173 is in use, trying 5174...

Configuration not found

Error: No helios.config.json found.
Run "helios init" to start a project.

Solution:

helios init

Components not loading

Ensure your framework is correctly set in helios.config.json:

{
  "framework": "react"
}

Studio filters components based on framework compatibility.

Registry connection errors

If the component registry is unreachable:

Fetching component registry (react)...
Warning: Failed to fetch components. Working offline.

You can still use Studio, but component installation will be unavailable.

Studio API

Studio exposes an API for component management:

Install component

await window.helios.installComponent('fade-in');

Remove component

await window.helios.removeComponent('fade-in');

Update component

await window.helios.updateComponent('fade-in');

Check installation status

const isInstalled = await window.helios.checkInstalled('fade-in');

Performance

Studio is optimized for development:

• Fast refresh - Changes reflect in milliseconds
• Lazy loading - Components load on demand
• Memory efficient - Minimal overhead during development

See also

• helios init - Initialize a project for Studio
• helios components - Browse components from CLI
• Component management - Install and manage components