> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/BintzGavin/helios/llms.txt
> Use this file to discover all available pages before exploring further.

# helios studio

> Launch the Helios Studio visual editor

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

## Usage

```bash theme={null}
helios studio [options]
```

## Options

<ParamField path="--port" type="number" default="5173">
  Port to listen on. Short form: `-p`.
</ParamField>

## 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

```bash theme={null}
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

```bash theme={null}
helios studio --port 3000
```

Starts Studio on port 3000 instead of the default 5173.

### Start Studio and open in browser

```bash theme={null}
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

```json theme={null}
{
  "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

```javascript theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
helios init
```

### Components not loading

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

```json theme={null}
{
  "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

```javascript theme={null}
await window.helios.installComponent('fade-in');
```

### Remove component

```javascript theme={null}
await window.helios.removeComponent('fade-in');
```

### Update component

```javascript theme={null}
await window.helios.updateComponent('fade-in');
```

### Check installation status

```javascript theme={null}
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](/api/cli-init) - Initialize a project for Studio
* [helios components](/api/cli-components) - Browse components from CLI
* [Component management](/api/cli-components) - Install and manage components