Skip to main content
Version 0.0.6: All operations require authentication. Consider upgrading to 0.0.7+ for free single file conversions.

​
Basic Usage

Version 0.0.6 uses a simple command structure without subcommands: 
next-lovable <source-directory> [target-directory] [options]

​
Examples

​
Basic Migration

Migrate to a new directory: 
next-lovable ./my-react-app ./my-next-app

​
In-Place Migration

Migrate in the same directory (be careful!): 
next-lovable ./my-react-app

​
Preview Changes First

See what will change without making modifications: 
next-lovable ./my-react-app --dry-run

​
Automated Migration

Skip confirmations and install dependencies: 
next-lovable ./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 ./my-app --dry-run
Output includes:
  • List of files to be converted
  • New file structure
  • Dependencies to be added/removed
  • Configuration changes
​
--yes, -y
boolean
Skip all confirmation prompts and proceed with migration automatically.Example:
next-lovable ./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 ./my-app ./next-app --install
Equivalent to running npm install in the target directory after migration.
​
--help, -h
boolean
Show help information and exit.Example:
next-lovable --help
​
--version, -v
boolean
Show version information and exit.Example:
next-lovable --version

​
Migration Process

​
What Happens During Migration

1

Project Analysis

  • Scans source directory for React components
  • Identifies React Router usage patterns
  • Analyzes component dependencies
  • Checks for common React patterns
2

File Structure Creation

  • Creates Next.js app directory structure
  • Sets up layout.tsx and page.tsx files
  • Organizes components appropriately
  • Creates necessary configuration files
3

Code Transformation

  • Converts React Router to Next.js navigation
  • Adds ‘use client’ directives where needed
  • Updates import statements
  • Transforms routing logic
4

Configuration Setup

  • Generates next.config.js
  • Updates package.json with Next.js scripts
  • Configures TypeScript (if used)
  • Sets up ESLint and other tools

​
File Structure Transformation

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

​
Code Transformations

​
React Router Conversion

import { BrowserRouter, Routes, Route, Link, useNavigate } from 'react-router-dom';

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();
  
  return (
    <nav>
      <Link to="/">Home</Link>
      <Link to="/about">About</Link>
      <button onClick={() => navigate('/contact')}>Contact</button>
    </nav>
  );
}

​
Package.json Updates

{
  "name": "my-react-app",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview"
  },
  "dependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "react-router-dom": "^6.8.0"
  },
  "devDependencies": {
    "@vitejs/plugin-react": "^3.1.0",
    "vite": "^4.1.0"
  }
}

​
Error Handling

The migration command includes comprehensive error handling:

​
Pre-Migration Validation

  • Source directory exists and contains a valid React project
  • Package.json validation - ensures React and React Router are present
  • Write permissions checked for target directory
  • Disk space verification
  • Network connectivity to API endpoints

​
During Migration

  • Syntax error detection - invalid components are reported
  • Dependency conflicts - version mismatches are handled
  • File permission issues - clear error messages
  • API failures - network issues are reported with suggestions

​
Post-Migration Verification

  • Generated code validation - ensures TypeScript/JavaScript is valid
  • Dependency installation - verifies all packages install correctly
  • Configuration testing - checks Next.js config is valid

​
Troubleshooting Common Issues

Problem: Cannot authenticate with APISolutions:
  1. Verify API key is correct from nextlovable.com
  2. Check network connectivity
  3. Try re-running next-lovable auth
  4. Contact support if account issues persist
Problem: Error about source directory not existingSolutions:
  1. Check the path is correct: ls -la ./my-react-app
  2. Use absolute paths if relative paths fail
  3. Ensure the directory contains a package.json file
  4. Verify you have read permissions
Problem: Cannot create target directorySolutions:
  1. Check write permissions in parent directory
  2. Ensure sufficient disk space
  3. Try using a different target location
  4. Run with elevated permissions if necessary
Problem: Migration stops partway throughSolutions:
  1. Check error messages for specific issues
  2. Ensure stable network connection
  3. Try migration without --install flag first
  4. Run --dry-run to identify potential issues
Problem: npm run dev fails in migrated projectSolutions:
  1. Run npm install to ensure dependencies
  2. Check for TypeScript errors: npx tsc --noEmit
  3. Clear Next.js cache: rm -rf .next
  4. Review next.config.js for issues

​
Best Practices

Always Dry Run First

Use --dry-run to preview changes before applying them

Backup Your Code

Commit to git or create a backup before migration

Test Incrementally

Test the migrated app thoroughly before deployment

Review Generated Code

Check the converted components for any needed adjustments

​
Migration Checklist

1

Pre-Migration

  • Backup original project
  • Verify authentication works
  • Run dry-run to preview changes
  • Check disk space and permissions
2

During Migration

  • Monitor for error messages
  • Ensure stable network connection
  • Don’t interrupt the process
3

Post-Migration

  • Install dependencies if not done automatically
  • Test development server starts
  • Verify all routes work correctly
  • Check for TypeScript/linting errors
  • Test build process

​
Upgrading to Version 0.0.7+

Consider upgrading for enhanced features:

Free Conversions

Single file conversions without authentication

Better CLI

Subcommand structure with more options

Granular Control

Choose specific transformations to apply

Improved Performance

Faster processing and better error handling

​
Need Help?

Troubleshooting Guide

Common issues and solutions

GitHub Issues

Report bugs and request features
⌘I