# Migration Guide

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"`.

```bash
starwind migrate
```

> **Info:** It is recommended to read [Migrating Astro Projects to Starwind UI v3](/blog/migrating-to-starwind-ui-v3/) before you
start. It covers the prerequisites and the application changes that require manual review after
the command finishes.

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

```astro
```

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

```bash
starwind add button
starwind update button
starwind primitives add button
starwind docs button
```