Skip to main content

Starwind UI v3.0 beta is now available! Read the migration guide

On this page

Migration Guide

View Markdown

Use starwind migrate when a project still has the old Astro copied-component setup. The command migrates as much as it safely can in one guided run and leaves anything unresolved in config as source: "legacy".

Terminal window
starwind migrate

What The Command Does

  • Reads starwind.config.json and detects the legacy config shape.
  • Inspects the public component directory, normally src/components/starwind.
  • Offers to back up existing component folders to src/components/starwind-legacy.
  • Creates a numbered backup such as src/components/starwind-legacy-1 if the default backup path already exists.
  • Asks before overwriting folders that conflict with Runtime registry components.
  • Leaves unrelated custom folders alone.
  • Installs the package requirements declared by the Runtime registry.
  • Writes a v2 config with framework: "astro" as the Runtime output target.

Public Import Paths

Migration keeps the public component path at src/components/starwind by default. Existing imports such as this should remain the normal public shape after migration:

---
import { Button } from "@/components/starwind/button";
---

Backup And Overwrite Prompts

The backup prompt protects your old component source before replacement. If you accept it, the CLI copies the current Starwind component folder before writing Runtime-backed styled components.

The overwrite prompt is per conflicting component folder. If you decline an overwrite, that folder stays in place and the component remains recorded as legacy-astro in the final report.

Migration Report

The final report separates the important outcomes:

  • Migrated: Runtime-backed styled components written successfully.
  • Skipped: Conflicting component folders that were not overwritten.
  • Backed up: folders copied into a legacy backup directory.
  • Overwritten: component folders replaced by the Runtime-backed registry artifact.
  • Custom: folders in the Starwind directory that were not registry components.
  • Legacy: unresolved entries that remain in config with source: "legacy".

After Migration

Use the normal Runtime CLI commands after migration:

Terminal window
starwind add button
starwind update button
starwind primitives add button
starwind docs button