next-lovable/README.md

Cross-platform tool to migrate Lovable React projects to Next.js with credit-free single file conversion

# 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

```bash
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:

```bash
# 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:
```bash
next-lovable <source-directory> [target-directory]
```

### Single File Conversion 📁

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

```bash
# 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)

```bash
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

```bash
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

1. **Authentication & Validation** (Full Migration Only)
   - Account verification
   - Project structure validation
   - Dependencies check

2. **Smart Analysis**
   - Route structure analysis
   - Component classification
   - Context provider detection
   - Client/Server boundary identification

3. **Automated Transformations**
   - React Router to App Router conversion
   - Layout structure creation
   - Component migrations
   - Dependency updates
   - Configuration generation

4. **Post-Migration Setup** (Full Migration Only)
   - Next.js configuration
   - TypeScript adjustments
   - Development environment setup

## Workflow Examples

### Testing Individual Components

```bash
# 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

```bash
# 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

1. Review generated files in `src/app`
2. Test with `npm run dev`
3. Check converted routes
4. Verify component functionality

## Real-World Examples

### Converting a React Router Navigation Component

**Before** (React Router):
```tsx
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`:
```tsx
'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**:
```tsx
import { Helmet } from 'react-helmet';

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

**After**:
```tsx
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

1. **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

2. **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

3. **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

4. **Incremental Approach**
   ```bash
   # 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