hulla.dev

Guide

Install your first component

Add editable UI components to an Astro project.

On this page

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.

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.

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.

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:

Terminal
export PATH="$PWD/node_modules/.bin:$PATH"

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.

Terminal
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.

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.

Terminal
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 for other framework targets.

4. Put the component on a page

The files are installed; now use them. Follow Build a reading counter to compose Card and Button into a working Astro page. You can skip its UI initialization step because you’ve already done it here.

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, specify component names and framework targets explicitly.

Use UI components for registry pinning and updates, or Configuration to understand the generated settings.