Install

npm install -g mv3-migrate

Or run directly with npx (no installation required):

npx mv3-migrate analyze ./my-extension

Usage

The CLI has two commands: analyze and migrate.

Analyze your extension

Scan an MV2 extension directory and get a detailed migration report:

mv3-migrate analyze ./my-extension

Save the report to a file:

mv3-migrate analyze ./my-extension -o migration-report.md

Migrate your manifest

Preview changes with a dry run:

mv3-migrate migrate ./my-extension --dry-run

Apply the migration. A backup of the original manifest.json is created automatically:

mv3-migrate migrate ./my-extension

Skip the backup if you prefer:

mv3-migrate migrate ./my-extension --no-backup

Usage Examples

Before: MV2 manifest.json

{
  "manifest_version": 2,
  "name": "My Extension",
  "version": "1.0",
  "background": {
    "scripts": ["background.js"],
    "persistent": true
  },
  "browser_action": {
    "default_icon": "icon.png",
    "default_title": "My Extension"
  },
  "permissions": [
    "storage",
    "https://*/*",
    "webRequestBlocking"
  ],
  "content_security_policy": "script-src 'self' https://example.com; object-src 'self'"
}

After: MV3 manifest.json

{
  "manifest_version": 3,
  "name": "My Extension",
  "version": "1.0",
  "background": {
    "service_worker": "background.js"
  },
  "action": {
    "default_icon": "icon.png",
    "default_title": "My Extension"
  },
  "permissions": [
    "storage",
    "declarativeNetRequest"
  ],
  "host_permissions": [
    "https://*/*"
  ],
  "content_security_policy": {
    "extension_pages": "script-src 'self' https://example.com; object-src 'self'"
  }
}

⚠️ Note: Some changes require manual work after migration:

• Background scripts must be converted to service workers (event-driven, no DOM)
• webRequest blocking must be migrated to declarativeNetRequest rules

Library API

Use mv3-migrate programmatically in your own tools:

import { analyzeExtension, migrateManifest, generateReport } from 'mv3-migrate';
import * as fs from 'fs';

// Analyze an extension directory
const analysis = analyzeExtension('./my-extension');
console.log(`Found ${analysis.stats.totalIssues} issues`);
console.log(`  Critical: ${analysis.stats.critical}`);
console.log(`  Warnings: ${analysis.stats.warning}`);

// Generate a markdown report
const report = generateReport(analysis);
fs.writeFileSync('report.md', report);

// Migrate a manifest object
const manifest = JSON.parse(fs.readFileSync('manifest.json', 'utf-8'));
const result = migrateManifest(manifest);

console.log('Changes applied:', result.changes);
console.log('Warnings:', result.warnings);

Exported Types

• AnalysisResult — Full analysis with issues and statistics
• MigrationIssue — Single issue with severity, category, description, and action
• MigrationResult — Migrated manifest, list of changes, and warnings

Project Structure

mv3-migrate/
├── src/
│   ├── analyzer.ts         # Analyzes MV2 extensions for migration issues
│   ├── cli.ts              # CLI entry point (commander)
│   ├── index.ts            # Library exports
│   ├── report.ts           # Generates markdown reports
│   └── transforms/
│       └── manifest.ts     # Manifest V2 → V3 conversion logic
├── package.json
├── tsconfig.json
└── README.md

Development

# Clone and install
git clone https://github.com/theluckystrike/mv3-migrate.git
cd mv3-migrate
npm install

# Build
npm run build

# Run tests
npm test

# Run linter
npm run lint

# Watch mode for development
npm run dev

Related Projects

• chrome-extension-starter-mv3 — Start fresh with an MV3 template
• chrome-storage-plus — Enhanced Chrome storage wrapper
• tab-manager-api — Chrome tabs API wrapper

License

MIT. See LICENSE for details.

Built at zovo.one by theluckystrike