Skip to main content

Starwind UI v3.0 is now available! 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.
  • Overwrites registered conflicts after a successful backup, because the previous folders are then recoverable. If you decline the backup, it asks about bulk and individual conflict overwrites.
  • 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.
  • Applies registry-declared public rename codemods when you approve them.

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.

After a successful backup, registered component conflicts are overwritten without another prompt. If you decline the backup, the CLI first offers to overwrite all conflicts. Declining that bulk overwrite opens a prompt for each conflicting component. Any component you keep remains in place and is written to config with source: "legacy".

When the registry declares a public component rename, migration can scan project source files and offer to update matching component import paths and exported names. Component folders, backup directories, generated output, dependencies, and starwind.config.json are excluded from that codemod scan.

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: the Starwind component directory copied into a legacy backup directory.
  • Custom: folders in the Starwind directory that were not registry components.
  • Legacy: unresolved entries that remain in config with source: "legacy".
  • Updated project imports/usages: registry-declared rename codemods that changed source files.
  • Skipped import/usage updates: rename codemods that you declined.
  • No matching imports/usages found: approved rename codemods that found nothing to change.

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