Convert Command

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

string

required

The React file you want to convert. Supports .tsx, .ts, .jsx, and .js files.

string

Output file path. If not specified, the original file is overwritten.Examples:

--output ./converted/MyComponent.tsx
-o ../next-version/Header.tsx

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

boolean

Preview changes without modifying any files. Great for testing.Example:

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

boolean

Show a detailed before/after comparison. Must be used with --dry-run.Example:

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

boolean

List all available transformations and exit.Example:

next-lovable convert --list

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>
  );
};

'use client';

import Link from 'next/link';
import { useRouter, usePathname } from 'next/navigation';

const MyComponent = () => {
  const router = useRouter();
  const pathname = usePathname();
  
  return (
    <div>
      <Link href="/dashboard">Dashboard</Link>
      <button onClick={() => router.push('/settings')}>Settings</button>
      <p>Current: {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>
);

import Head from 'next/head';

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

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>
  );
};

'use client';

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>
  );
};

'use client';

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?

Try More Examples

Explore real-world conversion examples

Learn Full Migration

Ready for complete project migration? See the migrate command

Read Best Practices

Check out our best practices guide

Choose Your Migration

Quick Start

Full Backend Migration

Production Optimization

Pricing & Credits

Basic Usage

Examples

Simple Conversion

Preview Changes First

Convert with Specific Transformations

Save to Different Location

Command Options

Transformation Types

router

helmet

client

context

Common Use Cases

Testing Before Full Migration

Batch Processing

Incremental Migration

Output Examples

Dry Run Output

Diff Output

Tips & Best Practices

Always Preview First

Test Individual Transformations

Keep Backups

Start Small

Error Handling

What’s Next?

​Basic Usage

​Examples

​Simple Conversion

​Preview Changes First

​Convert with Specific Transformations

​Save to Different Location

​Command Options

​Transformation Types

​router

​helmet

​client

​context

​Common Use Cases

​Testing Before Full Migration

​Batch Processing

​Incremental Migration

​Output Examples

​Dry Run Output

​Diff Output

​Tips & Best Practices

Always Preview First

Test Individual Transformations

Keep Backups

Start Small

​Error Handling

​What’s Next?

Basic Usage

Examples

Simple Conversion

Preview Changes First

Convert with Specific Transformations

Save to Different Location

Command Options

Transformation Types

router

helmet

client

context

Common Use Cases

Testing Before Full Migration

Batch Processing

Incremental Migration

Output Examples

Dry Run Output

Diff Output

Tips & Best Practices

Error Handling

What’s Next?