The
migrate
command performs full project migrations and requires authentication and credits. For free single file conversions, use the convert
command.Basic Usage
Examples
Basic Migration
Migrate to a new directory:In-Place Migration
Migrate in the same directory (be careful!):Preview Changes First
See what will change without making modifications:Automated Migration
Skip confirmations and install dependencies:Command Options
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
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
Simulate the migration without making any actual changes. Shows you exactly what files will be created, modified, or removed.Example:Output includes:
- List of files to be converted
- New file structure
- Dependencies to be added/removed
- Configuration changes
- Estimated credit consumption
Skip all confirmation prompts and proceed with migration automatically.Example:Use with caution - this will proceed without asking for confirmation.
Automatically install dependencies after migration completes.Example:Equivalent to running
npm install
in the target directory after migration.Comma-separated list of transformations to apply during migration. Available options:
router
- React Router to Next.js navigationhelmet
- React Helmet to Next.js Headclient
- Auto-detect and add ‘use client’ directivecontext
- React Context provider migrationall
- Apply all transformations (default)
--transform router,client
--transform all
-t helmet,context
Show help information for the migrate command.Example:
Migration Process
What Happens During Migration
1
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
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
- Preserves assets and public files
3
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
4
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
Code Transformations
React Router to App Router
Package.json Migration
Differences from v0.0.6
Subcommand Structure
v0.0.7+ uses
migrate
subcommand vs direct command in v0.0.6Granular Control
Choose specific transformations with
--transform
optionBetter 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
Authentication Issues
Problem: Cannot authenticate or invalid API keySolutions:
- Re-run authentication:
next-lovable auth
- Verify API key from nextlovable.com dashboard
- Check network connectivity to api.nextlovable.com
- Ensure account has sufficient credits
Source Project Not Recognized
Source Project Not Recognized
Problem: Tool doesn’t detect React Router projectSolutions:
- Verify package.json contains React and React Router dependencies
- Check that components actually use React Router hooks/components
- Ensure project structure follows standard React conventions
- Try running from the project root directory
Target Directory Issues
Target Directory Issues
Problem: Cannot create or access target directorySolutions:
- Check write permissions in parent directory
- Ensure sufficient disk space available
- Try using a different target location
- Avoid special characters in directory names
During Migration
Migration Stalls or Fails
Migration Stalls or Fails
Problem: Process hangs or stops with errorsSolutions:
- Check network connectivity
- Verify API rate limits aren’t exceeded
- Try smaller project or exclude large files temporarily
- Use
--dry-run
to identify potential issues first
Syntax Errors in Source
Syntax Errors in Source
Problem: Migration fails due to invalid source codeSolutions:
- Fix TypeScript/JavaScript errors first
- Run linting and fix issues
- Remove or fix experimental language features
- Ensure all imports resolve correctly
Credit Consumption High
Credit Consumption High
Problem: Migration uses more credits than expectedSolutions:
- Use
--dry-run
to estimate credits first - Remove unused files and components
- Consider migrating in phases
- Optimize complex routing patterns
Post-Migration
Generated App Won't Start
Generated App Won't Start
Problem:
npm run dev
fails in migrated projectSolutions:- Run
npm install
to ensure all dependencies - Check for TypeScript compilation errors
- Clear Next.js cache:
rm -rf .next
- Verify next.config.js is valid
- Check for missing environment variables
Routing Issues
Routing Issues
Problem: Pages don’t load or navigation brokenSolutions:
- Verify App Router structure (app/page.tsx files)
- Check that page components export default functions
- Ensure ‘use client’ directives are added where needed
- Verify Link components use
href
instead ofto
TypeScript Errors
TypeScript Errors
Problem: Type errors in migrated codeSolutions:
- Install missing type packages:
@types/react
,@types/node
- Update tsconfig.json for Next.js compatibility
- Fix component prop types
- Address Next.js-specific type requirements
Best Practices
Always Dry Run First
Use
--dry-run
to preview all changes and estimate creditsBackup 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
1
Pre-Migration
- Backup original project (git commit or copy)
- Verify authentication:
next-lovable auth
- Run dry-run:
next-lovable migrate ./app --dry-run
- Review estimated credit usage
- Check disk space and permissions
2
During Migration
- Monitor terminal output for errors
- Ensure stable network connection
- Don’t interrupt the migration process
- Note any warnings or issues reported
3
Post-Migration
- Install dependencies:
npm install
- Test development server:
npm run dev
- Verify all routes work correctly
- Check for TypeScript/linting errors
- Test build process:
npm run build
- Review and test all converted components
Advanced Usage
Selective Transformations
Apply only specific transformations:Batch Processing
Migrate multiple projects:Integration with CI/CD
What’s Next?
1
Test Your Migrated App
Thoroughly test all routes and functionality in your new Next.js app
2
Optimize Performance
Review and optimize server/client components for better performance
3
Deploy
Deploy your new Next.js app to your preferred hosting platform
4
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