---
title: Getting Started
description: Install Initium in a shadcn project and build your first AI-ready page workflow.
slug: getting-started
order: 1
---

# Getting Started

Initium gives your shadcn project a shared design direction, installable styles, production-ready blocks, and agent skills that help AI tools build with the same constraints your team uses.

This guide is the shortest path from an existing app to a working Initium setup.

## What You Need

- A React, Next.js, or compatible app that can use shadcn.
- shadcn initialized in the project.
- Access to the Initium app: the [Style Builder](https://app.initium.sh/), the [Strategy Builder](https://app.initium.sh/strategy), and the [Blocks browser](https://app.initium.sh/blocks).
- An `INITIUM_LICENSE_KEY` if you want to install pro blocks or the Initium skill pack.

If your app does not have shadcn yet, start with [Registry Setup](./install-shadcn-and-registry.md).

## Free And Pro Access

| Item | Access | Notes |
| --- | --- | --- |
| Style Builder exports | Free | Generates a custom registry URL for your selected style preset. |
| `DESIGN.md` | Free | Exported from the Style Builder and used as visual guidance for AI tools. |
| Strategy Builder exports | Free | Generates `STRATEGY.md` for audience, offer, positioning, and page structure. |
| Base Initium styles | Free | Installable as `@initium/initium-styles`. |
| Styled buttons and forms | Free | Installable through the Initium registry namespace. |
| Pro blocks | Pro | Require `INITIUM_LICENSE_KEY`. |
| Initium skills | Pro | Installed as `@initium/initium-agent` and require `INITIUM_LICENSE_KEY`. |

Free registry items can be installed without a license key. Pro items return an authorization error until your project has `INITIUM_LICENSE_KEY` available.

## 1. Initialize shadcn

If your project already has `components.json`, shadcn is already initialized. If not, initialize it first:

```bash
npx shadcn@latest init
```

Choose settings that match your app. Initium is installed through the shadcn registry system, so shadcn must be working before you install Initium items.

## 2. Add The Initium Registry

Add the Initium registry namespace to your project's `components.json`:

```json
{
  "registries": {
    "@initium": {
      "url": "https://app.initium.sh/r/styles/{style}/{name}.json",
      "headers": {
        "Authorization": "Bearer ${INITIUM_LICENSE_KEY}"
      }
    }
  }
}
```

Keep the authorization header even if you start with free items. Free installs still work, and pro installs will work once the license key is available.

The `{style}` placeholder is filled in by the shadcn CLI from your project's `style` setting. Initium components are built on Base UI, and projects on a `base-*` style (the default for new shadcn projects) receive them directly. Projects on a `radix-*` or legacy style receive the Radix build of the registry, which is maintained for existing customers but no longer receives new blocks.

## 3. Install Your Style

For a custom style, open the Style Builder, choose your colors, fonts, type scale, radius scale, buttons, and forms, then copy the generated shadcn install command.

The command uses a generated registry URL:

```bash
npx shadcn@latest add "https://app.initium.sh/r/preset?code=..."
```

You can also install the base Initium style utilities:

```bash
npx shadcn@latest add @initium/initium-styles
```

Install styles before blocks so classes such as `wrapper`, `tagline`, `paragraph`, `heading-xl`, and `heading-lg` are available. Rich text article blocks additionally install the `@initium/typeset` stylesheet as a dependency; import it after Tailwind in your global CSS (`@import "./typeset.css";`).

## 4. Export Your AI Assets

From the Style Builder, export `DESIGN.md`. From the Strategy Builder, export `STRATEGY.md`.

Place both files in your project root while you work:

```txt
DESIGN.md
STRATEGY.md
```

You do not have to commit these files. Treat them as working files that your AI tool can read before generating or revising UI.

## 5. Install The Initium Skill Pack

If you have a license key, install the Initium skill pack:

```bash
npx shadcn@latest add @initium/initium-agent
```

This installs the skill into:

```txt
.agents/skills/initium/
```

Use the skill when your AI tool supports project skills. If it does not, tell the tool to read `.agents/skills/initium/SKILL.md`.

## 6. Install Blocks

Install blocks through the same registry namespace:

```bash
npx shadcn@latest add @initium/hero-section-1
```

Use the Blocks browser to choose the exact block name. Pro blocks require `INITIUM_LICENSE_KEY`.

## 7. Start A Chat With Your AI Tool

Start by telling your AI tool what to read:

```txt
Read DESIGN.md and STRATEGY.md from the project root.
Follow the installed Initium skill if available.
Use Initium blocks for major sections and keep the installed style preset intact.
```

Then ask for a specific page or section. The more specific your target audience, offer, proof, and conversion goal are, the better the result will be.

## Package Manager Notes

Examples use `npx shadcn@latest`. If your project prefers another package manager, use the matching shadcn runner:

```bash
pnpm dlx shadcn@latest add @initium/hero-section-1
yarn dlx shadcn@latest add @initium/hero-section-1
bunx --bun shadcn@latest add @initium/hero-section-1
```