Installation

# Installation

This guide walks you through setting up Starwind Pro so you can start installing blocks in minutes.

## Prerequisites

Before you begin, make sure you have:

- An Astro project (create one with `npm create astro@latest`)
- Node.js 20+ installed
- A Starwind Pro license (purchased from the [website](/pricing/))

> **Info:** Free blocks work without a license. You only need a Pro license for premium
blocks.

## Step 1: Initialize Starwind Pro

Choose your preferred setup method. Both methods end up at [Step 2: Get Your License Key](#step-2-get-your-license-key).

### CLI Setup (Recommended)

From your project root, run the init command with the `--pro` flag:

```bash
npx starwind@latest init --pro
```

This sets up the Starwind Pro registry alongside the free components, allowing you to install premium blocks.

> **Info:** If you haven't set up Starwind UI yet, this command will initialize the base
configuration in addition to Starwind Pro setup.

**Tip:** If using pnpm, it is recommended to create a `.npmrc` file in the root of your project with the following content:

```text title=".npmrc"
auto-install-peers=true
node-linker=hoisted
lockfile=true
```

Once complete, [skip to Step 2](#step-2-get-your-license-key).

### Manual Setup

If you prefer full control, you can configure the registry yourself.

You'll first need Starwind UI set up in your project. See the [Starwind UI installation docs](https://starwind.dev/docs/getting-started/installation/) for instructions.

Starwind Pro is implemented as a private shadcn registry. Open or create your `components.json` and add the following to the `registries` object:

```json title="components.json"
{
  "$schema": "https://ui.shadcn.com/schema.json",
  "registries": {
    "@starwind-pro": {
      "url": "https://pro.starwind.dev/r/{name}",
      "headers": {
        "Authorization": "Bearer ${STARWIND_LICENSE_KEY}"
      }
    }
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils"
  },
  "tailwind": {
    "config": "",
    "css": "src/styles/starwind.css",
    "baseColor": "neutral",
    "cssVariables": true
  },
  "style": "default",
  "rsc": true
}
```

Then create a `.env.local` file in your project root with your license key:

```bash title=".env.local"
# Starwind Pro registry setup
STARWIND_LICENSE_KEY=your_starwind_pro_license_key
```

Replace `your_starwind_pro_license_key` with your actual key (see Step 2 below). A valid license key is **not** required for free blocks.

> **Caution:** Never commit your `.env.local` file to version control. Make sure it's listed
in your `.gitignore` file.

## Step 2: Get Your License Key

There are a few ways to retrieve your Starwind Pro license key. Once retrieved, add it to your `.env.local` file.

### Fetch Your License Key Here

If you're signed in with Starwind Pro access, you can fetch your license key directly:

<LicenseKeyLoader />

### From the Account Dashboard

1. Sign in to your account and go to [pro.starwind.dev/account/](/account/)
2. Scroll down to the **"Getting Started with Starwind Pro"** section
3. Click the **"Get License Key"** button
4. Your license key will appear in the code block below

<video
class="aspect-1386/452 h-auto w-full rounded-lg"
width="1386"
height="452"
controls
loading="lazy"
>
<source src={get_license_key} type="video/mp4" />
</video>

### From the Polar Dashboard

1. Go to your account page at [pro.starwind.dev/account/](/account/)
2. Click **"Access Polar Portal"** in the Quick Actions card
3. Find your license key in the Polar customer portal

![Polar portal button](./polar_portal_button.jpg)

> **Tip:** Your license key is tied to your account. Keep it secure and don't share it
publicly.

## Step 3: Install Blocks

You're all set. Browse the [component library](/components/) and install any block with the CLI:

```bash
npx starwind@latest add @starwind-pro/hero-01
```

<video
class="aspect-1190/1090 h-auto w-full rounded-lg"
width="1190"
height="1090"
controls
muted
loading="lazy"
>
<source src={install_component_flow} type="video/mp4" />
</video>

> **Info:** You can find the exact install command on each block's demo page. Click the
copy button and paste it into your terminal.

## Next Steps

- Browse the [component library](/components/) to see all available blocks
- Having issues? Check the [Troubleshooting](/docs/getting-started/troubleshooting/) page
- Join [the community](https://discord.gg/hYxyyFHNJb) for support and updates