Skip to main content
The migrate command runs automated migrations on your shadcn/ui components. Use it to update components when there are breaking changes or to adopt new features.

​
Usage

shadcn migrate [migration] [path]

​
Arguments

​
migration
string
The migration to run. Use --list to see available migrations.
​
path
string
Optional path or glob pattern to migrate. If not provided, migrates all components.

​
Options

​
--cwd
string
The working directory. Defaults to the current directory.
​
--list
boolean
default:"false"
List all available migrations.
​
--yes
boolean
default:"false"
Skip confirmation prompt.

​
Available migrations

​
icons

Migrate your UI components to a different icon library. 
shadcn migrate icons

​
radix

Migrate to Radix UI. 
shadcn migrate radix

​
rtl

Migrate your components to support RTL (right-to-left) languages. 
shadcn migrate rtl

​
Examples

​
List available migrations

shadcn migrate --list
Output: 
Available migrations:
- icons: migrate your ui components to a different icon library.
- radix: migrate to radix-ui.
- rtl: migrate your components to support RTL (right-to-left).

​
Run a specific migration

shadcn migrate icons

​
Migrate specific files

shadcn migrate rtl components/ui/button.tsx

​
Migrate using glob pattern

shadcn migrate rtl "components/ui/**/*.tsx"

​
Skip confirmation

shadcn migrate icons --yes

​
Migrate in specific directory

shadcn migrate rtl --cwd ./my-project

​
Migration details

​
Icon library migration

Migrates components from one icon library to another. Common migrations:
  • Lucide React → Other icon libraries
  • React Icons → Lucide React
What it does:
  • Updates import statements
  • Replaces icon components
  • Maintains icon props and styling

​
Radix UI migration

Migrates components to use Radix UI primitives. What it does:
  • Updates Radix UI package imports
  • Adjusts component composition
  • Updates event handlers and props

​
RTL migration

Adds right-to-left language support to components. What it does:
  • Adds direction-aware styling
  • Updates logical properties (e.g., margin-left → margin-inline-start)
  • Adjusts layout for bidirectional support
  • Updates icon positioning and animations

​
Before running migrations

​
1. Commit your changes

Always commit your code before running migrations: 
git add .
git commit -m "Before migration"

​
2. Review migration scope

Understand which files will be affected: 
# Check which components exist
ls components/ui/

​
3. Backup your components

cp -r components/ui components/ui.backup

​
After running migrations

​
1. Review changes

git diff

​
2. Test your components

Ensure all components work as expected: 
npm run dev

​
3. Update imports

Some migrations may require updating imports in your application code.

​
4. Run tests

npm test

​
Requirements

  • Valid components.json file in your project root
  • Project must not be empty
  • Must run from project root or use --cwd

​
Error handling

If migration fails:
  1. No components.json found 
    No `components.json` file found. Ensure you are at the root of your project.
    Solution: Run from project root or run shadcn init first.
  2. Invalid migration 
    You must specify a valid migration. Run `shadcn migrate --list` to see available migrations.
    Solution: Check available migrations with --list.
  3. Empty project 
    No `components.json` file found. Ensure you are at the root of your project.
    Solution: Initialize project with shadcn init.

​
Notes

  • Migrations modify files in place
  • Always backup before running migrations
  • Some migrations may require manual adjustments
  • Review all changes before committing
  • Migrations are idempotent (safe to run multiple times)

Build docs developers (and LLMs) love

Get started for freeTalk to us