# Install your first component

> Add editable UI components to an Astro project.

## What you'll build

An Astro project with a pinned CLI, shared UI settings, and editable button source.

### Before you start

- Bun installed, even if your project uses npm, pnpm, or Yarn.
- An Astro application with its dependencies installed.

Add a Button to an Astro page using the `hulla` CLI. The command copies the component into your project, where you can edit its source.

## 1. Install the pinned beta

Install the CLI as a development dependency in the application. The exact beta pin keeps team members and CI on the same CLI release; the `hulla` CLI itself requires Bun at runtime.

### Install with bun

```sh
bun add -D hulla@0.0.0-beta.1
```

### Install with npm

```sh
npm install --save-dev hulla@0.0.0-beta.1
```

### Install with pnpm

```sh
pnpm add -D hulla@0.0.0-beta.1
```

### Install with yarn

```sh
yarn add -D hulla@0.0.0-beta.1
```

Verify the installed executable before changing the project. These equivalent commands run the same pinned version through each package manager; Bun must be available even when the project uses npm, pnpm, or Yarn.

### Install with bun

```sh
bunx hulla@0.0.0-beta.1 --version
```

### Install with npm

```sh
npx hulla@0.0.0-beta.1 --version
```

### Install with pnpm

```sh
pnpm dlx hulla@0.0.0-beta.1 --version
```

### Install with yarn

```sh
yarn dlx hulla@0.0.0-beta.1 --version
```

The command prints `hulla v0.0.0-beta.1`. Keep that exact version in your project so another install uses the same CLI behavior.

Package scripts can find a locally installed `hulla` executable automatically. For the terminal commands below, add the project's executable directory to your current shell's search path. Run this from the project root:

```sh
export PATH="$PWD/node_modules/.bin:$PATH"
```

## 2. Initialize project settings

From the project root, create `.hulla/hulla.json`. The `--yes` flag accepts confirmations and prevents prompts; for this initialization, the CLI detects the package manager and records its package scripts.

```sh
hulla init --yes
```

The success signal is a new `.hulla/hulla.json` containing the package scripts and references to subsystem configuration. Commit this file so local development and automation use the same choices.

## 3. Configure and add a component

Run UI setup from the same project to choose the registry, framework, component paths, and support files. Then add a component by its registry name; specify the framework whenever the registry contains that component in more than one target.

```sh
hulla ui init
hulla ui add --framework astro button
```

The add command copies the Astro button's files and any declared dependencies or support files into the configured paths. Review the changed files and run the application's build or type checks so missing peer setup is visible in your own project. Use [UI components](https://hulla.dev/docs/cli/ui.md) for other framework targets.

## 4. Put the component on a page

The files are installed; now use them. Follow [Build a reading counter](https://hulla.dev/guides/ui/quick-start.md) to compose Card and Button into a working Astro page. You can skip its UI initialization step because you've already done it here.

> **Warning: Review before accepting overwrites**
>
> `--yes` accepts confirmations, including replacement or deletion where a command supports them. Leave it off while exploring a setup. In [automation](https://hulla.dev/docs/cli/automation.md), specify component names and framework targets explicitly.

Use [UI components](https://hulla.dev/docs/cli/ui.md) for registry pinning and updates, or [Configuration](https://hulla.dev/docs/cli/configuration.md) to understand the generated settings.