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.
Learn how to create your own components and publish them to a custom registry.
Component structure
A component is defined by the ComponentDefinition interface:
interface ComponentDefinition {
name: string;
description?: string;
type: 'react' | 'vue' | 'svelte' | 'solid' | 'vanilla';
files: ComponentFile[];
dependencies?: Record<string, string>;
registryDependencies?: string[];
}
interface ComponentFile {
name: string;
content: string;
}
Creating a component
Define the component
Create a new component definition:const myComponent: ComponentDefinition = {
name: 'countdown',
description: 'Display a countdown timer',
type: 'react',
files: [
{
name: 'Countdown.tsx',
content: `import React from 'react';
import { useVideoFrame } from './useVideoFrame';
import { Helios } from '@helios-project/core';
interface CountdownProps {
helios?: Helios;
targetFrame?: number;
}
export const Countdown: React.FC<CountdownProps> = ({
helios,
targetFrame = 300
}) => {
const frame = useVideoFrame(helios);
const remaining = Math.max(0, targetFrame - frame);
return <div>{remaining} frames remaining</div>;
};
`
}
],
dependencies: {
'react': '^18.0.0',
'@helios-project/core': 'latest'
},
registryDependencies: ['use-video-frame']
};
Add to local registry
For testing, add your component to the local registry manifest:// packages/cli/src/registry/manifest.ts
export const registry: ComponentDefinition[] = [
// ... existing components
myComponent
];
Test locally
Test your component by installing it: Publishing a registry
Create registry index
Build a registry index file (index.json):{
"version": "1.0.0",
"components": [
{
"name": "countdown",
"description": "Display a countdown timer",
"type": "react",
"files": ["countdown/Countdown.tsx"],
"dependencies": {
"react": "^18.0.0",
"@helios-project/core": "latest"
},
"registryDependencies": ["use-video-frame"]
}
]
}
Host component files
Place component files at the paths specified in the index:registry/
├── index.json
└── countdown/
└── Countdown.tsx
Deploy to hosting
Upload your registry to static hosting:# Example: Deploy to GitHub Pages, Vercel, Netlify, S3, etc.
# Make sure index.json and component files are publicly accessible
Configure users
Users point to your registry in helios.config.json:{
"registry": "https://your-domain.com/registry/index.json"
}
{
"version": "1.0.0",
"components": [
{
"name": "timer",
"description": "Video timecode display",
"type": "react",
"files": ["timer/Timer.tsx"],
"dependencies": { ... },
"registryDependencies": ["use-video-frame"]
}
]
}
[
{
"name": "timer",
"type": "react",
"files": [
{
"name": "Timer.tsx",
"content": "...full file content..."
}
]
}
]
Authentication
For private registries, set an environment variable:
export HELIOS_REGISTRY_TOKEN="your-token"
Authorization: Bearer your-token
Best practices
- Keep components focused - One component per responsibility
- Document props - Use TypeScript interfaces and JSDoc comments
- Minimize dependencies - Fewer npm packages = easier installation
- Use registry dependencies - Reuse common utilities like
use-video-frame
- Test thoroughly - Install components in a real project before publishing
- Version carefully - Consider semantic versioning for breaking changes
Example registry structure
my-registry/
├── index.json
├── timer/
│ └── Timer.tsx
├── progress-bar/
│ └── ProgressBar.tsx
├── watermark/
│ └── Watermark.tsx
└── use-video-frame/
└── useVideoFrame.ts
Timeout and fallback
The registry client has a 5-second timeout. If fetching fails:
- The CLI falls back to the local built-in registry
- Users see a warning but can still use default components
Ensure your registry hosting is reliable and fast.
Multi-framework support
Publish variants for different frameworks:
{
"components": [
{
"name": "timer",
"type": "react",
"files": ["timer/Timer.tsx"]
},
{
"name": "timer",
"type": "vue",
"files": ["timer/Timer.vue"]
}
]
}