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

> Initialize a new Helios project configuration

The `init` command creates a new Helios project or adds Helios configuration to an existing project.

## Usage

```bash theme={null}
helios init [target] [options]
```

## Arguments

<ParamField path="target" type="string" optional>
  Target directory for the project. If omitted, uses the current directory.
</ParamField>

## Options

<ParamField path="--yes" type="boolean" default="false">
  Skip prompts and use defaults (React framework). Useful for automated workflows.
</ParamField>

<ParamField path="--framework" type="string">
  Specify framework without prompts. Valid values: `react`, `vue`, `svelte`, `solid`, `vanilla`.
</ParamField>

<ParamField path="--example" type="string">
  Initialize from an example project. Downloads and sets up a complete example.
</ParamField>

<ParamField path="--repo" type="string" default="BintzGavin/helios/examples">
  Example repository to download from. Format: `user/repo` or `user/repo/path`.
</ParamField>

## Interactive mode

When run without flags, `helios init` presents an interactive setup:

1. Choose between scaffolding a new project or downloading an example
2. Select your framework (React, Vue, Svelte, Solid, or Vanilla)
3. Configure component and library directories

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

```
How do you want to start?
❯ Scaffold a new project (from template)
  Download an example

Which framework are you using?
❯ React
  Vue
  Svelte
  Solid
  Vanilla

Where would you like to install components? (src/components/helios)
Where is your lib directory? (src/lib)
```

## Examples

### Create a new React project

```bash theme={null}
helios init my-video-app
cd my-video-app
npm install
npm run dev
```

### Quick start with defaults

```bash theme={null}
helios init my-project --yes
```

This creates a React project with default settings:

* Framework: React
* Components directory: `src/components/helios`
* Lib directory: `src/lib`

### Specify a framework

```bash theme={null}
helios init --framework vue
```

### Initialize from an example

```bash theme={null}
helios init --example basic-animation
```

This downloads the `basic-animation` example from the default repository.

### Use a custom example repository

```bash theme={null}
helios init --example my-template --repo myorg/helios-templates
```

### Add Helios to an existing project

```bash theme={null}
cd existing-project
helios init
```

If a `package.json` exists, Helios will detect the framework and only create the configuration file.

## Configuration file

The command creates `helios.config.json`:

```json theme={null}
{
  "version": "1.0.0",
  "framework": "react",
  "directories": {
    "components": "src/components/helios",
    "lib": "src/lib"
  },
  "components": [],
  "dependencies": {}
}
```

### Configuration options

<ParamField path="version" type="string">
  Configuration schema version. Currently `1.0.0`.
</ParamField>

<ParamField path="framework" type="string">
  Project framework: `react`, `vue`, `svelte`, `solid`, or `vanilla`.
</ParamField>

<ParamField path="directories.components" type="string">
  Path where Helios components will be installed.
</ParamField>

<ParamField path="directories.lib" type="string">
  Path to the lib/utils directory.
</ParamField>

<ParamField path="components" type="array">
  List of installed component names.
</ParamField>

<ParamField path="dependencies" type="object">
  Component dependencies and their versions.
</ParamField>

<ParamField path="registry" type="string" optional>
  Custom component registry URL.
</ParamField>

## Project templates

Each framework template includes:

* `package.json` with required dependencies
* `composition.html` entry point
* `vite.config.js` build configuration
* `index.html` development server entry
* Framework-specific component examples
* TypeScript configuration

### Template structure

```
my-project/
├── src/
│   ├── components/
│   │   └── helios/          # Helios components
│   ├── lib/                 # Utilities
│   └── composition.tsx      # Main composition
├── composition.html         # Entry point
├── helios.config.json      # Helios configuration
├── package.json
├── tsconfig.json
└── vite.config.js
```

## Next steps

After initialization:

1. Install dependencies:
   ```bash theme={null}
   npm install
   ```

2. Start the development server:
   ```bash theme={null}
   npm run dev
   ```

3. Or launch Studio:
   ```bash theme={null}
   helios studio
   ```

4. Add components:
   ```bash theme={null}
   helios add fade-in
   ```