---
title: Registry Setup
description: Prepare an existing or new shadcn project for Initium registry installs.
slug: install-shadcn-and-registry
order: 2
---

# Registry Setup

Initium installs through the shadcn registry system. Before adding styles, blocks, or skills, make sure shadcn works in your project and that `components.json` knows about the Initium registry.

## Existing shadcn Projects

If your project already has a `components.json` file, you can add Initium directly.

Open `components.json` and add the `@initium` registry:

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

Keep your existing `style`, `tailwind`, `aliases`, and other shadcn settings. Only add the `registries` entry or merge it with your existing registries.

The `{style}` placeholder is filled in automatically by the shadcn CLI from your project's `style` setting. Projects on a `base-*` style (the current default) receive Base UI components; projects on a `radix-*` or legacy style (`default`, `new-york`) receive the Radix build of the registry. If you configured Initium before the Base UI transition with the older `https://app.initium.sh/r/{name}.json` URL, it keeps working and always serves the Radix build — no change required.

## New Projects

If your project does not have shadcn yet, initialize shadcn first:

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

After shadcn creates `components.json`, add the Initium registry entry shown above.

## Free Blocks

The first block of every marketing block category is free. Blocks marked with the "Free" badge in the [blocks browser](/blocks) install without a license key, together with everything they depend on (Initium styles, the media component, and placeholder logos).

Copy the install command from any free block's preview card, for example:

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

The remaining blocks in each category and all example pages are pro items and require a license key.

## License Key

Free Initium items can be installed without a license key. Pro blocks and the Initium skill pack require `INITIUM_LICENSE_KEY`.

For local development, set the key in your shell or in your local environment file:

```bash
INITIUM_LICENSE_KEY=your_polar_license_key
```

Do not commit real license keys to your repository.

## Verify The Registry

Install a free item first to verify the registry is configured correctly:

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

Then install a pro item if you have a license key:

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

If the free item works but the pro item fails with an authorization error, the registry is configured correctly and the issue is the license key.

## Install Command Variants

Examples in these docs use `npx shadcn@latest`. Use your project's preferred package manager if needed:

```bash
pnpm dlx shadcn@latest add @initium/initium-styles
yarn dlx shadcn@latest add @initium/initium-styles
bunx --bun shadcn@latest add @initium/initium-styles
```

## What This Enables

After setup, your project can install:

- Custom style presets exported from the Style Builder.
- Base Initium styles with `@initium/initium-styles`.
- Free styled buttons and forms.
- The first block of every marketing category for free, such as `@initium/hero-section-1`.
- Pro blocks such as `@initium/hero-section-2`.
- The Initium skill pack with `@initium/initium-agent`.