Skip to main content

Starwind UI v3.0 is now available! Migration guide

Manual Setup

Use this guide when you want to create the files that starwind init normally manages. Complete the shared setup here, then follow your framework guide for aliases, CSS imports, Tailwind wiring, and theme initialization.

Install the Shared Packages

Choose the adapter for the component source that you will add to the project. Astro components use @starwind-ui/astro. Every supported React host uses @starwind-ui/react. Vue 3.5 projects use @starwind-ui/vue@beta. Svelte 5 projects use @starwind-ui/svelte@beta and require Svelte 5.29 or newer within Svelte 5.

The adapter package installs the matching Starwind Runtime dependency. Your framework starter continues to own the host framework packages. The Vue and Svelte packages use the beta npm channel; CLI commands continue to use starwind@latest.

Create the Project Configuration

Create starwind.config.json in the project root. Select the tab that matches the generated component source.

These paths work for Vite projects. For SvelteKit, set componentDir to src/lib/starwind. Other project types can use different paths; follow your framework guide below. Astro keeps framework: "astro" and uses componentDirs for React, Vue, or Svelte components.

The CLI adds entries to components and primitives when you install source. Keep those arrays under CLI control so starwind update can compare the installed versions with the registry.

Create the Shared Stylesheet

Create src/styles/starwind.css with the Starwind foundation below. It loads Tailwind CSS v4, animation utilities, form styles, semantic color tokens, radii, dark mode, and Sidebar tokens.

Show the complete stylesheet
src/styles/starwind.css
@import "tailwindcss";
@import "tw-animate-css";
@plugin "@tailwindcss/forms";
@custom-variant dark (&:where(.dark, .dark *));
@theme {
--animate-accordion-down: accordion-down 0.2s ease-out;
--animate-accordion-up: accordion-up 0.2s ease-out;
@keyframes accordion-down {
from {
height: 0;
}
to {
height: var(--starwind-accordion-content-height);
}
}
@keyframes accordion-up {
from {
height: var(--starwind-accordion-content-height);
}
to {
height: 0;
}
}
}
@theme inline {
--color-background: var(--background);
--color-foreground: var(--foreground);
--color-card: var(--card);
--color-card-foreground: var(--card-foreground);
--color-popover: var(--popover);
--color-popover-foreground: var(--popover-foreground);
--color-primary: var(--primary);
--color-primary-foreground: var(--primary-foreground);
--color-primary-accent: var(--primary-accent);
--color-secondary: var(--secondary);
--color-secondary-foreground: var(--secondary-foreground);
--color-secondary-accent: var(--secondary-accent);
--color-muted: var(--muted);
--color-muted-foreground: var(--muted-foreground);
--color-accent: var(--accent);
--color-accent-foreground: var(--accent-foreground);
--color-info: var(--info);
--color-info-foreground: var(--info-foreground);
--color-success: var(--success);
--color-success-foreground: var(--success-foreground);
--color-warning: var(--warning);
--color-warning-foreground: var(--warning-foreground);
--color-error: var(--error);
--color-error-foreground: var(--error-foreground);
--color-border: var(--border);
--color-input: var(--input);
--color-outline: var(--outline);
--radius-xs: calc(var(--radius) - 0.375rem);
--radius-sm: calc(var(--radius) - 0.25rem);
--radius-md: calc(var(--radius) - 0.125rem);
--radius-lg: var(--radius);
--radius-xl: calc(var(--radius) + 0.25rem);
--radius-2xl: calc(var(--radius) + 0.5rem);
--radius-3xl: calc(var(--radius) + 1rem);
--color-sidebar: var(--sidebar-background);
--color-sidebar-foreground: var(--sidebar-foreground);
--color-sidebar-primary: var(--sidebar-primary);
--color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
--color-sidebar-accent: var(--sidebar-accent);
--color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
--color-sidebar-border: var(--sidebar-border);
--color-sidebar-outline: var(--sidebar-outline);
}
:root {
--background: var(--color-white);
--foreground: var(--color-neutral-950);
--card: var(--color-white);
--card-foreground: var(--color-neutral-950);
--popover: var(--color-white);
--popover-foreground: var(--color-neutral-950);
--primary: var(--color-blue-700);
--primary-foreground: var(--color-neutral-50);
--primary-accent: var(--color-blue-700);
--secondary: var(--color-neutral-200);
--secondary-foreground: var(--color-neutral-950);
--secondary-accent: var(--color-neutral-950);
--muted: var(--color-neutral-100);
--muted-foreground: var(--color-neutral-600);
--accent: var(--color-neutral-100);
--accent-foreground: var(--color-neutral-900);
--info: var(--color-sky-300);
--info-foreground: var(--color-sky-950);
--success: var(--color-green-300);
--success-foreground: var(--color-green-950);
--warning: var(--color-amber-300);
--warning-foreground: var(--color-amber-950);
--error: var(--color-red-700);
--error-foreground: var(--color-neutral-50);
--border: var(--color-neutral-200);
--input: var(--color-neutral-200);
--outline: var(--color-neutral-400);
--radius: 0.625rem;
--sidebar-background: var(--color-neutral-50);
--sidebar-foreground: var(--color-neutral-950);
--sidebar-primary: var(--color-blue-700);
--sidebar-primary-foreground: var(--color-neutral-50);
--sidebar-accent: var(--color-neutral-100);
--sidebar-accent-foreground: var(--color-neutral-900);
--sidebar-border: var(--color-neutral-200);
--sidebar-outline: var(--color-neutral-400);
}
.dark {
--background: var(--color-neutral-950);
--foreground: var(--color-neutral-50);
--card: var(--color-neutral-900);
--card-foreground: var(--color-neutral-50);
--popover: var(--color-neutral-900);
--popover-foreground: var(--color-neutral-50);
--primary: var(--color-blue-700);
--primary-foreground: var(--color-neutral-50);
--primary-accent: var(--color-blue-400);
--secondary: var(--color-neutral-800);
--secondary-foreground: var(--color-neutral-50);
--secondary-accent: var(--color-neutral-50);
--muted: var(--color-neutral-800);
--muted-foreground: var(--color-neutral-400);
--accent: var(--color-neutral-700);
--accent-foreground: var(--color-neutral-50);
--info: var(--color-sky-300);
--info-foreground: var(--color-sky-950);
--success: var(--color-green-300);
--success-foreground: var(--color-green-950);
--warning: var(--color-amber-300);
--warning-foreground: var(--color-amber-950);
--error: var(--color-red-800);
--error-foreground: var(--color-neutral-50);
--border: --alpha(var(--color-neutral-50) / 10%);
--input: --alpha(var(--color-neutral-50) / 15%);
--outline: var(--color-neutral-500);
--sidebar-background: var(--color-neutral-900);
--sidebar-foreground: var(--color-neutral-50);
--sidebar-primary: var(--color-blue-700);
--sidebar-primary-foreground: var(--color-neutral-50);
--sidebar-accent: var(--color-neutral-800);
--sidebar-accent-foreground: var(--color-neutral-100);
--sidebar-border: var(--color-neutral-800);
--sidebar-outline: var(--color-neutral-600);
}
@layer base {
* {
@apply border-border outline-outline/50;
}
body {
@apply bg-background text-foreground scheme-light dark:scheme-dark;
}
button {
@apply cursor-pointer;
}
}

The Theming guide explains how to change the tokens after the base stylesheet works in your application.

Wire the Framework

Complete the host-specific setup for your project:

These sections configure aliases, stylesheet imports, Tailwind, and the prepaint theme script. They also document host-specific source paths when a project does not use src/.

Add a Component

After the shared and framework setup is complete, use the CLI to install component source and keep the config version records current.