Using components

Add and use components from the Helios registry

Learn how to discover, install, and use components from the Helios component registry.

Prerequisites

Before adding components, initialize your project:

helios init

This creates a helios.config.json file in your project root.

Browsing components

List all available components:

helios components

Search for specific components:

helios components timer

Filter by framework:

helios components --framework react

Show components for all frameworks:

helios components --all

Adding components

1. Install a component

   Run the add command with the component name:

   helios add timer
   

   This will:

   • Fetch the component from the registry
   • Resolve and install registry dependencies (like use-video-frame)
   • Copy files to your src/components/helios directory
   • Install npm dependencies
   • Update helios.config.json
2. Review installed files

   Check your components directory:

   src/components/helios/
   ├── Timer.tsx
   └── useVideoFrame.ts
   

   The timer component depends on use-video-frame, so both were installed.

3. Import and use

   Import the component in your code:

   import { Timer } from './components/helios/Timer';
   
   function MyVideo({ helios }) {
     return (
       <div>
         <Timer helios={helios} />
       </div>
     );
   }
   

Skip dependency installation

If you want to manage dependencies yourself:

helios add timer --no-install

The component files will be copied, but npm packages won’t be installed automatically.

Dependency resolution

Components can depend on:

1. npm dependencies - External packages (e.g., react, @helios-project/core)
2. Registry dependencies - Other components in the registry (e.g., use-video-frame)

The CLI automatically resolves the entire dependency tree. If component A depends on component B, both are installed when you run helios add A.

Framework detection

The CLI reads your framework setting from helios.config.json:

{
  "framework": "react"
}

When adding components, it prioritizes:

1. Exact framework match (e.g., react)
2. Vanilla/framework-agnostic components
3. Falls back if no match found

Configuration file

After adding components, helios.config.json tracks what’s installed:

{
  "version": "1.0.0",
  "directories": {
    "components": "src/components/helios",
    "lib": "src/lib"
  },
  "framework": "react",
  "components": ["use-video-frame", "timer"],
  "dependencies": {
    "use-video-frame": "latest",
    "timer": "latest"
  }
}

Modifying components

Once copied, components belong to you. Edit them directly:

• Change styles
• Add props
• Remove unused features
• Combine multiple components

No need to fork or submit PRs - you own the code.

Updating components

Re-running helios add <component> will skip existing files by default. To overwrite:

# Manually delete and re-add
rm src/components/helios/Timer.tsx
helios add timer

Currently, there’s no automatic update mechanism. You own the code, so updates are manual.