next-lovable

next-lovable

An intelligent CLI tool to automatically migrate React applications to Next.js 13+ (App Router), specializing in React Router to App Router conversions.

Key Features

• 🚀 Smart React Router to Next.js App Router conversion
• 📦 Automated migration from Vite to Next.js build system
• 🔄 Intelligent component transformation with 'use client' directives
• 📁 NEW in v0.7+: Single file conversion with credit tracking
• 🎯 Automatic handling of:
  • Route configurations
  • Layouts and page structures
  • Package dependencies
  • React Helmet to Next.js Metadata
  • Client/Server component separation

Prerequisites

• Node.js 18.x or higher
• npm or yarn
• A nextlovable.com account (for full project migrations)
• A React project using:
  • React Router
  • Vite
  • TypeScript (optional but recommended)

Installation

npm install -g next-lovable

Authentication

Authentication with your nextlovable.com account is required for all conversions:

• Login will be prompted on first use
• Sessions are securely stored for future use
• Automatic token refresh handling
• Required for both file conversion and full project migration

Credit System

• Initial credits: 10 file conversion credits when you sign up
• Credit packages: Each migration credit purchased grants 10 additional file conversion credits
• Usage: 1 file conversion credit consumed per file converted (dry-run is free)
• Balance: Check your current balance during conversion

Usage

New in v0.0.7+: Command Structure

Starting from version 0.0.7, the CLI uses subcommands:

# Full project migration (requires auth + migration credits)
next-lovable migrate <source-directory> [target-directory]

# Single file conversion (requires auth + file conversion credits)  
next-lovable convert <file> [options]

# Check your file conversion credit balance
next-lovable credits

Note: In versions before 0.6, use the legacy format:

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

Single File Conversion 📁

Convert individual React files to Next.js with credit tracking:

# Convert a single component (consumes 1 file conversion credit)
next-lovable convert MyComponent.tsx

# Save to different location
next-lovable convert MyComponent.tsx --output ./converted/MyComponent.tsx

# Apply specific transformations only
next-lovable convert MyComponent.tsx --transform router,client

# Preview changes without consuming credits
next-lovable convert MyComponent.tsx --dry-run --show-diff

# List available transformations (no auth required)
next-lovable convert --list

Available Transformations

• router: React Router → Next.js Router (useNavigate, Link, etc.)
• helmet: React Helmet → Next.js Head
• client: Add "use client" directive where needed
• context: Context provider transformations
• all: Apply all transformations (default)

Single File Options

• -o, --output <path>: Output file path (default: overwrite input)
• -t, --transform <types>: Comma-separated transformations (default: all)
• -d, --dry-run: Preview changes without modification
• --show-diff: Show before/after comparison (with --dry-run)
• --legacy: Use legacy transformers instead of enhanced ones
• --list: List available transformations

Full Project Migration

Dry Run Mode (Recommended First Step)

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

The --dry-run option provides:

• 🔍 Complete project analysis
• 📝 Detailed migration report
• ⚠️ Potential issue warnings
• 📊 List of files to be modified
• 🎯 Preview of transformations
• 0️⃣ No actual changes made

Complete Migration

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

Project Migration Options

• -y, --yes: Skip confirmation prompts
• -i, --install: Install dependencies after migration
• -d, --dry-run: Simulation mode without changes
• -e, --enhanced: Use enhanced migration (default)
• --legacy: Use legacy migration mode
• --help: Show help information

Migration Process

• Authentication & Validation (Full Migration Only)

  • Account verification
  • Project structure validation
  • Dependencies check

• Smart Analysis

  • Route structure analysis
  • Component classification
  • Context provider detection
  • Client/Server boundary identification

• Automated Transformations

  • React Router to App Router conversion
  • Layout structure creation
  • Component migrations
  • Dependency updates
  • Configuration generation

• Post-Migration Setup (Full Migration Only)

  • Next.js configuration
  • TypeScript adjustments
  • Development environment setup

Workflow Examples

Testing Individual Components

# Test router conversion on a specific component (free with dry-run)
next-lovable convert src/components/Navigation.tsx --dry-run

# Convert only routing-related code (consumes 1 credit)
next-lovable convert src/pages/Dashboard.tsx --transform router --output ./test-output.tsx

# Preview all transformations with diff (free)
next-lovable convert src/App.tsx --dry-run --show-diff

Before Full Migration

# 0. Check your file conversion credit balance
next-lovable credits

# 1. Test key components individually (free with dry-run)
next-lovable convert src/App.tsx --dry-run
next-lovable convert src/components/Layout.tsx --dry-run

# 2. Run full project dry-run (consumes migration credits)
next-lovable migrate ./my-react-app --dry-run

# 3. Execute full migration
next-lovable migrate ./my-react-app ./next-app --install

Intelligent Features

• 🧠 Smart component analysis for 'use client' directives
• 🔄 Automatic context provider migration
• 📱 Layout preservation and enhancement
• 🛠️ Dependency resolution and cleanup
• 🎯 Typescript support and type preservation
• ⚡ Enhanced transformers (v0.6+):
  • Advanced React Router pattern detection
  • Smarter client/server component separation
  • Better handling of complex routing scenarios
  • Improved template literal preservation in routes

Transformation Details

Router Conversion (router)

• useNavigate() → useRouter() from next/navigation
• <Link to="/path"> → <Link href="/path"> from next/link
• useLocation() → usePathname() + useSearchParams()
• useParams() → Next.js useParams()
• Template literals in paths preserved: to={\/user/${id}`}→href={`/user/${id}`}`

Helmet Conversion (helmet)

• <Helmet> → <Head> from next/head
• Meta tags and title preservation
• SEO attributes maintained

Client Directive (client)

• Automatic "use client" directive addition
• Smart detection of client-side features:
  • React hooks (useState, useEffect, etc.)
  • Event handlers (onClick, onChange, etc.)
  • Browser APIs (window, document, localStorage)
  • Third-party client libraries

Post-Migration

• Review generated files in src/app
• Test with npm run dev
• Check converted routes
• Verify component functionality

Real-World Examples

Converting a React Router Navigation Component

Before (React Router):

import { Link, useNavigate, useLocation } from 'react-router-dom';

export const Navigation = () => {
  const navigate = useNavigate();
  const location = useLocation();

  return (
    <nav>
      <Link to="/dashboard">Dashboard</Link>
      <Link to={`/profile/${userId}`}>Profile</Link>
      <button onClick={() => navigate('/settings')}>
        Settings
      </button>
      <p>Current: {location.pathname}</p>
    </nav>
  );
};

After (Next.js) - using next-lovable convert:

'use client';

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

export const Navigation = () => {
  const router = useRouter();
  const pathname = usePathname();

  return (
    <nav>
      <Link href="/dashboard">Dashboard</Link>
      <Link href={`/profile/${userId}`}>Profile</Link>
      <button onClick={() => router.push('/settings')}>
        Settings
      </button>
      <p>Current: {pathname}</p>
    </nav>
  );
};

Converting React Helmet SEO Component

Before:

import { Helmet } from 'react-helmet';

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

After:

import Head from 'next/head';

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

Quick Command Reference

Task	Command	Credits Required
List transformations	next-lovable convert --list	❌ No
Check credit balance	next-lovable credits	❌ No (auth required)
Test single file	next-lovable convert MyComponent.tsx --dry-run	❌ No
Convert single file	next-lovable convert MyComponent.tsx	✅ 1 file credit
Preview project migration	next-lovable migrate ./my-app --dry-run	✅ Migration credits
Full project migration	next-lovable migrate ./my-app ./next-app	✅ Migration credits

Limitations

• Complex custom route configurations may need manual adjustments
• Dynamic route parameters might require review
• Some third-party integrations may need updates
• Complex state management setups might need fine-tuning

Best Practices

• Start with Dry-Run Testing (Free)

  • Test key components individually with convert --dry-run
  • No credits consumed for dry-run operations
  • Perfect for understanding what changes will be made

• Efficient Credit Usage

  • Use dry-run mode extensively before actual conversion
  • Convert multiple files at once when possible
  • Plan your transformations to minimize credit usage

• Full Project Migration

  • Always run migrate --dry-run first
  • Keep a backup of your original project
  • Review generated files before deployment
  • Test thoroughly after migration

• Incremental Approach

  # Test individual files first (free with dry-run)
  next-lovable convert src/App.tsx --dry-run
  next-lovable convert src/components/*.tsx --dry-run
  
  # Convert specific files (consumes file credits)
  next-lovable convert src/App.tsx
  next-lovable convert src/components/Navigation.tsx
  
  # Then migrate the full project (consumes migration credits)
  next-lovable migrate ./my-react-app --dry-run
  next-lovable migrate ./my-react-app ./next-app --install
  

Version Notes

• v0.6+: New subcommand structure (migrate, convert)
• v0.5 and earlier: Legacy command format (direct arguments)
• v0.6+: File conversion with credit tracking system added
• Credit System: 10 initial credits + 10 credits per migration credit purchased