Migrate Command - Next-Lovable

The migrate command performs full project migrations and requires authentication and credits. For free single file conversions, use the convert command.

Basic Usage

next-lovable migrate <source-directory> [target-directory] [options]

Examples

Basic Migration

Migrate to a new directory:

next-lovable migrate ./my-react-app ./my-next-app

In-Place Migration

Migrate in the same directory (be careful!):

next-lovable migrate ./my-react-app

Preview Changes First

See what will change without making modifications:

next-lovable migrate ./my-react-app --dry-run

Automated Migration

Skip confirmations and install dependencies:

next-lovable migrate ./my-react-app ./my-next-app --yes --install

Command Options

source-directory

string

required

Path to your React application directory. Must contain a package.json file with React and React Router dependencies.Examples:

./my-react-app
/path/to/react-project
../frontend

target-directory

string

Directory where the new Next.js project will be created. If omitted, migration happens in-place in the source directory.Examples:

./my-next-app
/path/to/next-project
../next-frontend

Note: Directory will be created if it doesn’t exist.

--dry-run, -d

boolean

Simulate the migration without making any actual changes. Shows you exactly what files will be created, modified, or removed.Example:

next-lovable migrate ./my-app --dry-run

Output includes:

List of files to be converted
New file structure
Dependencies to be added/removed
Configuration changes
Estimated credit consumption

--yes, -y

boolean

Skip all confirmation prompts and proceed with migration automatically.Example:

next-lovable migrate ./my-app ./next-app --yes

Use with caution - this will proceed without asking for confirmation.

--install, -i

boolean

Automatically install dependencies after migration completes.Example:

next-lovable migrate ./my-app ./next-app --install

Equivalent to running npm install in the target directory after migration.

--transform, -t

string

Comma-separated list of transformations to apply during migration. Available options:

router - React Router to Next.js navigation
helmet - React Helmet to Next.js Head
client - Auto-detect and add ‘use client’ directive
context - React Context provider migration
all - Apply all transformations (default)

Examples:

--transform router,client
--transform all
-t helmet,context

--help, -h

boolean

Show help information for the migrate command.Example:

next-lovable migrate --help

Migration Process

What Happens During Migration

Project Analysis

Scans source directory for React components
Identifies React Router usage patterns
Analyzes component dependencies and structure
Detects client vs server component requirements
Estimates transformation complexity

File Structure Creation

Creates Next.js app directory structure
Sets up layout.tsx and page.tsx files
Organizes components appropriately
Creates necessary configuration files
Preserves assets and public files

Code Transformation

Converts React Router to Next.js navigation
Transforms routing components to pages
Adds ‘use client’ directives where needed
Updates import statements and paths
Converts React Helmet to Next.js Head

Configuration Setup

Generates next.config.js
Updates package.json with Next.js scripts
Configures TypeScript settings (if used)
Sets up ESLint and other development tools
Migrates environment variables

File Structure Transformation

my-react-app/
├── src/
│   ├── App.tsx
│   ├── main.tsx
│   ├── components/
│   │   ├── Header.tsx
│   │   └── Navigation.tsx
│   ├── pages/
│   │   ├── Home.tsx
│   │   ├── About.tsx
│   │   └── Contact.tsx
│   ├── hooks/
│   │   └── useAuth.ts
│   └── styles/
│       └── index.css
├── public/
├── package.json
└── vite.config.js

Code Transformations

React Router to App Router

// src/App.tsx
import { BrowserRouter, Routes, Route } from 'react-router-dom';
import { Link, useNavigate, useLocation } from 'react-router-dom';
import Home from './pages/Home';
import About from './pages/About';
import Contact from './pages/Contact';

function App() {
  return (
    <BrowserRouter>
      <Navigation />
      <Routes>
        <Route path="/" element={<Home />} />
        <Route path="/about" element={<About />} />
        <Route path="/contact" element={<Contact />} />
      </Routes>
    </BrowserRouter>
  );
}

function Navigation() {
  const navigate = useNavigate();
  const location = useLocation();
  
  return (
    <nav>
      <Link to="/">Home</Link>
      <Link to="/about">About</Link>
      <Link to="/contact">Contact</Link>
      <span>Current: {location.pathname}</span>
      <button onClick={() => navigate('/about')}>Go to About</button>
    </nav>
  );
}

Package.json Migration

{
  "name": "my-react-app",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview",
    "lint": "eslint src --ext ts,tsx"
  },
  "dependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "react-router-dom": "^6.8.0",
    "react-helmet": "^6.1.0"
  },
  "devDependencies": {
    "@vitejs/plugin-react": "^3.1.0",
    "vite": "^4.1.0",
    "typescript": "^4.9.0"
  }
}

Differences from v0.0.6

Subcommand Structure

v0.0.7+ uses migrate subcommand vs direct command in v0.0.6

Granular Control

Choose specific transformations with --transform option

Better Error Handling

Improved error messages and recovery options

Enhanced Performance

Faster processing and more efficient API usage

Command Comparison

Feature	v0.0.6	v0.0.7+
Command	`next-lovable <source>`	`next-lovable migrate <source>`
Free tier	❌ No	✅ Single file conversions
Transformations	All or nothing	Granular control
Error recovery	Limited	Enhanced
Dry run detail	Basic	Comprehensive

Error Handling & Troubleshooting

Pre-Migration Validation

Authentication Issues

Source Project Not Recognized

Target Directory Issues

During Migration

Migration Stalls or Fails

Syntax Errors in Source

Credit Consumption High

Post-Migration

Generated App Won't Start

Routing Issues

TypeScript Errors

Best Practices

Always Dry Run First

Use --dry-run to preview all changes and estimate credits

Backup Your Code

Commit to git or create backups before migration

Test Incrementally

Test converted components individually before full deployment

Review Generated Code

Check converted components for any needed manual adjustments

Migration Checklist

Advanced Usage

Selective Transformations

Apply only specific transformations:

# Only convert routing, skip client directive detection
next-lovable migrate ./my-app ./next-app --transform router

# Convert routing and helmet, skip context providers
next-lovable migrate ./my-app ./next-app --transform router,helmet

# Apply all transformations (default)
next-lovable migrate ./my-app ./next-app --transform all

Batch Processing

Migrate multiple projects:

# Using a loop
for dir in project1 project2 project3; do
  next-lovable migrate ./$dir ./migrated-$dir --yes
done

# With parallel processing (be careful with API limits)
find ./projects -name "package.json" -exec dirname {} \; | \
  xargs -I {} -P 3 next-lovable migrate {} {}-next --yes

Integration with CI/CD

# Example GitHub Actions workflow
name: Migrate to Next.js
on: workflow_dispatch

jobs:
  migrate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      
      - name: Install next-lovable
        run: npm install -g next-lovable
      
      - name: Authenticate
        run: echo "${{ secrets.NEXTLOVABLE_API_KEY }}" | next-lovable auth
      
      - name: Run migration
        run: next-lovable migrate ./react-app ./next-app --yes --install
      
      - name: Test build
        run: cd next-app && npm run build

What’s Next?

Test Your Migrated App

Thoroughly test all routes and functionality in your new Next.js app

Optimize Performance

Review and optimize server/client components for better performance

Deploy

Deploy your new Next.js app to your preferred hosting platform

Monitor & Iterate

Monitor the app in production and make necessary adjustments

Convert Command

Free single file conversions

Troubleshooting

Common issues and solutions

Best Practices

Tips for successful migrations

Need Help?

GitHub Issues

Report bugs and request features

Discord Community

Get help from the community

Getting Started

Commands

Guides

​Basic Usage

​Examples

​Basic Migration

​In-Place Migration

​Preview Changes First

​Automated Migration

​Command Options

​Migration Process

​What Happens During Migration

​File Structure Transformation

​Code Transformations

​React Router to App Router

​Package.json Migration

​Differences from v0.0.6

Subcommand Structure

Granular Control

Better Error Handling

Enhanced Performance

​Command Comparison

​Error Handling & Troubleshooting

​Pre-Migration Validation

​During Migration

​Post-Migration

​Best Practices

Always Dry Run First

Backup Your Code

Test Incrementally

Review Generated Code

​Migration Checklist

​Advanced Usage

​Selective Transformations

​Batch Processing

​Integration with CI/CD

​What’s Next?

Convert Command

Troubleshooting

Best Practices

​Need Help?

GitHub Issues

Discord Community

Basic Usage

Examples

Basic Migration

In-Place Migration

Preview Changes First

Automated Migration

Command Options

Migration Process

What Happens During Migration

File Structure Transformation

Code Transformations

React Router to App Router

Package.json Migration

Differences from v0.0.6

Command Comparison

Error Handling & Troubleshooting

Pre-Migration Validation

During Migration

Post-Migration

Best Practices

Migration Checklist

Advanced Usage

Selective Transformations

Batch Processing

Integration with CI/CD

What’s Next?

Need Help?