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:

{
  "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:

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 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:

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:

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:

npx shadcn@latest add @initium/initium-styles

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

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:

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.