🔄 lwc-convert

> A precision TypeScript CLI tool for converting Salesforce Aura components and Visualforce pages to Lightning Web Components (LWC)

Quick Start •
Features •
Mappings •
CLI Reference

---

lwc-convert automates the migration of legacy Salesforce UI technologies to modern Lightning Web Components:

| Source Technology | Target | Confidence |
|-------------------|--------|------------|
| Aura Components | LWC | High |
| Visualforce Pages | LWC | Medium-High |

$3

For each conversion, the tool generates a complete LWC bundle:

``
myComponent/
├── myComponent.html # Converted template
├── myComponent.js # ES6 class with decorators
├── myComponent.css # Scoped styles
├── myComponent.js-meta.xml # Component configuration
└── CONVERSION_NOTES.md # Action items & guidance
`

---

✨ Features

$3

Unlike batch tools that sacrifice accuracy, lwc-convert processes one component at a time for maximum precision and detailed error reporting.

$3

| Mode | Description | Best For |
|------|-------------|----------|
| Scaffolding (default) | Generates skeleton with // TODO: comments | Complex components requiring manual attention |
| Full Conversion (--full) | Complete transformation with // REVIEW: markers | Simple, standard components |

$3

- Parses Aura markup, controllers, helpers, and styles
- Analyzes Apex controllers for VF pages
- Detects patterns and suggests modern equivalents
- Identifies potential issues upfront
- New! 📊 Complexity Grading: Analyze components before conversion to estimate effort and identify risks
- New! 📈 CSV Export: Export grading reports for team tracking and stakeholder updates
- New! 🔔 Update Notifications: Get notified when new versions are available

$3

Every conversion includes a detailed markdown file with:

- ✅ Completed transformations
- ⚠️ Items needing manual attention
- 📖 Migration guidance and best practices

---

🚀 Quick Start

$3

Just run lwc-convert without arguments to launch the interactive TUI:

`bash
npx lwc-convert
`

You'll be guided through:

1. Select conversion type (Aura or Visualforce)
2. Choose component from auto-discovered list or enter path
3. Configure options (scaffolding/full, output dir, open folder)
4. Confirm and convert!

$3

- Node.js 18.0 or higher
- npm 8.0 or higher

$3

Via npm (recommended):

`bash


Run directly with npx (no install needed)

npx lwc-convert aura AccountCard

Or install globally

npm install -g lwc-convert
lwc-convert aura AccountCard
`

From source (for development):

`bash
git clone https://github.com/Lastonedown86/lwc-convert.git
cd lwc-convert
npm install
npm run build
npm link
`

$3

Convert an Aura Component:

`bash


Just use the component name — the CLI searches automatically!

lwc-convert aura AccountCard

Or use a full path

lwc-convert aura ./force-app/main/default/aura/AccountCard

Full conversion mode

lwc-convert aura AccountCard --full
`

Convert a Visualforce Page:

`bash


Just use the page name (with or without .page extension)

lwc-convert vf ContactList

With Apex controller (also supports just the class name)

lwc-convert vf ContactList --controller ContactListController

Or use full paths

lwc-convert vf ./pages/ContactList.page --controller ./classes/ContactListController.cls
`

Preview Without Writing Files:

`bash
lwc-convert aura MyComponent --dry-run --verbose
`

Assess Conversion Complexity:

`bash


Grade a single component

lwc-convert grade AccountCard --type aura

Scan entire project and export report

lwc-convert grade --type both --format json -o report.json

Export to CSV for team tracking (Excel/Sheets compatible)

lwc-convert grade --format csv -o migration-status.csv

Filter to only problematic components

lwc-convert grade --filter "grade:D,F" --format csv -o needs-attention.csv
`

> 💡 Smart Path Resolution: The CLI automatically searches common Salesforce project locations:
>
> - force-app/main/default/aura/, src/aura/, aura/
> - force-app/main/default/pages/, src/pages/, pages/
> - force-app/main/default/classes/, src/classes/, classes/

---

📖 CLI Reference

$3

`bash
lwc-convert # Launch interactive TUI
lwc-convert aura # Convert Aura component bundle
lwc-convert vf # Convert Visualforce page
lwc-convert grade [target] # Assess conversion complexity
lwc-convert deps [target] # Analyze component dependencies
lwc-convert session # View session info and patterns
`

$3

| Option | Description |
|--------|-------------|
| -V, --version | Display version |
| -h, --help | Show help |

$3

`bash
lwc-convert aura [options]
`

| Option | Description | Default |
|--------|-------------|---------|
| --full | Full conversion instead of scaffolding | false |
| -o, --output

| Output directory | ./lwc-output |
| --open | Open output folder in file explorer | false |
| --dry-run | Preview without writing files | false |
| --verbose | Show detailed logs | false |

$3

`bash
lwc-convert vf [options]
`

| Option | Description | Default |
|--------|-------------|---------|
| --full | Full conversion instead of scaffolding | false |
| -o, --output

| Output directory | ./lwc-output |
| --controller | Apex controller for enhanced analysis | — |
| --open | Open output folder in file explorer | false |
| --dry-run | Preview without writing files | false |
| --verbose | Show detailed logs | false |

$3

`bash
lwc-convert grade [target] [options]
`

| Option | Description | Default |
|--------|-------------|---------|
| -t, --type | Component type (aura, vf, both) | both |
| -o, --output | Output file for report | — |
| --format | Output format (json, csv, console) | console |
| --detailed | Show detailed breakdown | false |
| --sort-by | Sort by score, complexity, or name | score |
| --filter | Filter results (e.g., grade:D,F) | — |

$3

`bash
lwc-convert deps [target] [options]
`

| Option | Description | Default |
|--------|-------------|---------|
| -t, --type | Component type (aura, vf, both) | both |
| -o, --output | Output file path | — |
| --format | Output format (console, json, mermaid) | console |
| --conversion-order | Show recommended conversion order | false |
| --focus | Focus on specific component | — |
| --depth | Maximum depth to traverse (0 = unlimited) | 0 |
| --circular-only | Only show circular dependencies | false |

$3

`bash
lwc-convert session [options]
`

| Option | Description |
|--------|-------------|
| --report | Generate full session report |
| --patterns | Show learned patterns from session |
| --cleanup | Clean up session data |

---

🔄 Output Modes

$3

Generates an LWC skeleton optimized for manual completion:

`javascript
import { LightningElement, api } from 'lwc';

// TODO: Import Apex method - verify class and method name
// import getRecords from '@salesforce/apex/MyController.getRecords';

export default class MyComponent extends LightningElement {
// TODO: Verify if this should be @api (public) or private
@api recordId;

// Converted from aura:attribute "items"
items = [];

// TODO: Migrate logic from Aura init handler
connectedCallback() {
// Original init logic goes here
}

// TODO: Implement - converted from controller.handleSave
handleSave(event) {
// Original: component.get("v.record"), then server call
}
}
`

$3

Attempts complete code transformation:

`javascript
import { LightningElement, api, wire } from 'lwc';
import getRecords from '@salesforce/apex/MyController.getRecords';

export default class MyComponent extends LightningElement {
@api recordId;
items = [];
isLoading = false;

connectedCallback() {
this.loadRecords();
}

async loadRecords() {
this.isLoading = true;
try {
// REVIEW: Verify Apex method parameters
this.items = await getRecords({ recordId: this.recordId });
} catch (error) {
console.error('Error loading records:', error);
} finally {
this.isLoading = false;
}
}

handleSave(event) {
// REVIEW: Complex logic converted - verify behavior
const record = { ...this.currentRecord };
// ... conversion continues
}
}
`

---

📊 Migration Tracking

$3

Export grading results to CSV for tracking migration progress in spreadsheets:

`bash


Full project export

lwc-convert grade --format csv -o migration-status.csv

Only components needing attention

lwc-convert grade --filter "grade:D,F" --format csv -o needs-attention.csv
`

CSV includes:
- Component name, type, and file path
- Score (0-100) and letter grade (A-F)
- Complexity level and estimated manual hours
- Automated conversion percentage
- Warning count per component
- Summary section with totals and grade distribution

$3

Visualize component relationships and plan conversion order:

`bash


Show all dependencies

lwc-convert deps

Get recommended conversion order (leaves first)

lwc-convert deps --conversion-order

Focus on one component's dependency tree

lwc-convert deps --focus AccountCard

Export as Mermaid diagram for documentation

lwc-convert deps --format mermaid -o deps.md
`

$3

The tool learns patterns during your session to improve suggestions:

`bash


View session summary

lwc-convert session

See learned conversion patterns

lwc-convert session --patterns

Full session report

lwc-convert session --report
`

---

🔔 Update Notifications

Starting with v1.5.0, lwc-convert automatically checks for updates and notifies you when a new version is available:

`
╭───────────────────────────────────────────────╮
│ Update available: 1.5.0 → 1.6.0 │
│ Run npm i -g lwc-convert to update │
╰───────────────────────────────────────────────╯
`

- Non-blocking: Check runs in background, doesn't slow commands
- Cached: Only checks npm registry once per 24 hours
- Graceful: Silently skips if offline or npm is unreachable

---

📋 Conversion Mappings

$3

🏷️ Component Tags

| Aura | LWC |
|------|-----|
| |