Skip to main content
The convert command consumes 1 file conversion credit per file. Each new account starts with 10 free conversion credits, and every migration credit purchased grants 10 additional conversion credits.

​
Basic Usage

next-lovable convert <file> [options]

​
Examples

​
Simple Conversion

Convert a single file: 
next-lovable convert src/components/Header.tsx

​
Preview Changes First

See what will change without modifying the file: 
next-lovable convert src/components/Header.tsx --dry-run --show-diff

​
Convert with Specific Transformations

Apply only specific transformation types: 
next-lovable convert MyComponent.tsx --transform router,client

​
Save to Different Location

Keep the original file intact: 
next-lovable convert src/Header.tsx --output converted/Header.tsx

​
Command Options

​
file
string
required
The React file you want to convert. Supports .tsx, .ts, .jsx, and .js files.
​
--output, -o
string
Output file path. If not specified, the original file is overwritten.Examples:
  • --output ./converted/MyComponent.tsx
  • -o ../next-version/Header.tsx
​
--transform, -t
string
Comma-separated list of transformations to apply. 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
  • --transform router,client
  • -t helmet,context
​
--dry-run, -d
boolean
Preview changes without modifying any files. Great for testing.Example:
next-lovable convert Header.tsx --dry-run
​
--show-diff
boolean
Show a detailed before/after comparison. Must be used with --dry-run.Example:
next-lovable convert Header.tsx --dry-run --show-diff
​
--list
boolean
List all available transformations and exit.Example:
next-lovable convert --list
​
--help, -h
boolean
Show help information for the convert command.

​
Transformation Types

​
router

Converts React Router usage to Next.js navigation: 
import { Link, useNavigate, useLocation } from 'react-router-dom';

const MyComponent = () => {
  const navigate = useNavigate();
  const location = useLocation();
  
  return (
    <div>
      <Link to="/dashboard">Dashboard</Link>
      <button onClick={() => navigate('/settings')}>Settings</button>
      <p>Current: {location.pathname}</p>
    </div>
  );
};

​
helmet

Converts React Helmet to Next.js Head: 
import { Helmet } from 'react-helmet';

const PageMeta = ({ title, description }) => (
  <Helmet>
    <title>{title}</title>
    <meta name="description" content={description} />
  </Helmet>
);

​
client

Automatically detects when a component needs the 'use client' directive: 
import React, { useState } from 'react';

const Counter = () => {
  const [count, setCount] = useState(0);
  
  return (
    <button onClick={() => setCount(count + 1)}>
      Count: {count}
    </button>
  );
};
Client directive is added when the component uses:
  • React hooks (useState, useEffect, etc.)
  • Event handlers (onClick, onChange, etc.)
  • Browser APIs (window, document, localStorage)
  • Third-party libraries that require client-side execution

​
context

Migrates React Context providers and consumers: 
import React, { createContext, useContext } from 'react';

const ThemeContext = createContext();

export const ThemeProvider = ({ children }) => {
  const [theme, setTheme] = useState('light');
  
  return (
    <ThemeContext.Provider value={{ theme, setTheme }}>
      {children}
    </ThemeContext.Provider>
  );
};

​
Common Use Cases

​
Testing Before Full Migration

Before migrating an entire project, test key components: 
# Test your main App component
next-lovable convert src/App.tsx --dry-run --show-diff

# Test navigation components
next-lovable convert src/components/Navigation.tsx --dry-run

# Test components with routing
find src -name "*.tsx" -exec next-lovable convert {} --dry-run \;

​
Batch Processing

Convert multiple files at once: 
# Convert all files in a directory
next-lovable convert src/components/*.tsx

# Convert with specific transformations only
next-lovable convert src/pages/*.tsx --transform router

​
Incremental Migration

Gradually migrate your codebase: 
# Step 1: Convert routing components
next-lovable convert src/App.tsx src/components/Navigation.tsx --transform router

# Step 2: Convert components with state
next-lovable convert src/components/Form.tsx --transform client

# Step 3: Convert metadata components
next-lovable convert src/components/SEO.tsx --transform helmet

​
Output Examples

​
Dry Run Output

$ next-lovable convert Header.tsx --dry-run

✓ Analyzed Header.tsx
✓ Found React Router usage - will convert to Next.js navigation
✓ Detected client-side hooks - will add 'use client' directive
✓ No changes needed for imports

Summary:
- 3 transformations will be applied
- File size will change from 1.2KB to 1.3KB
- No breaking changes detected

Use --show-diff to see detailed changes

​
Diff Output

$ next-lovable convert Header.tsx --dry-run --show-diff

--- Header.tsx (original)
+++ Header.tsx (converted)
@@ -1,4 +1,6 @@
+'use client';
+
 import React from 'react';
-import { Link, useNavigate } from 'react-router-dom';
+import Link from 'next/link';
+import { useRouter } from 'next/navigation';

@@ -6,7 +8,7 @@
 const Header = () => {
-  const navigate = useNavigate();
+  const router = useRouter();
   
   return (
-    <Link to="/dashboard">Dashboard</Link>
+    <Link href="/dashboard">Dashboard</Link>
   );
 };

​
Tips & Best Practices

Always Preview First

Use --dry-run --show-diff to see changes before applying them

Test Individual Transformations

Use --transform to apply specific changes and understand what each does

Keep Backups

Use --output to save converted files separately when testing

Start Small

Begin with simple components before tackling complex files

​
Error Handling

The convert command includes robust error handling:
  • Syntax errors: The tool will report and skip files with syntax errors
  • Unsupported patterns: Complex patterns are reported for manual review
  • File permissions: Clear error messages for permission issues
  • Invalid options: Helpful suggestions for incorrect command usage

​
What’s Next?

1

Try More Examples

Explore real-world conversion examples
2

Learn Full Migration

Ready for complete project migration? See the migrate command
3

Read Best Practices

Check out our best practices guide
⌘I