Local-first CLI release

Ship MV2 to MV3 migrations with proof, not guesswork.

mv3migrate scans a Chrome extension, rewrites the common MV2 patterns, flags the dangerous ones, and produces a report you can hand to a developer or use to keep moving locally.

Run locally See validation Report issue

manifest rewriteJS codemodsrisk scannerHTML report

mv3migrate / free run output

$ node ./src/cli.js ./tests/fixtures/simple-popup --out ./out --report ./report.html

{
  "plan": "free",
  "license": null,
  "inputDir": "./tests/fixtures/simple-popup",
  "outDir": "./out",
  "reportPath": "./report.html",
  "patchPath": null,
  "manifestChanges": [
    "browser_action/page_action -> action",
    "background.scripts -> background.service_worker",
    "host permissions moved to host_permissions"
  ],
  "manifestWarnings": [
    "background.scripts requires a service worker rewrite"
  ],
  "summary": {
    "critical": 0,
    "warning": 0,
    "info": 1
  }
}

Plan

free

Warnings

Info

Report

./report.html

What it does not do

It does not pretend every MV2 extension is a safe auto-convert. When migration is ambiguous, it leaves a warning instead of hiding the risk.

Local validation

The current MVP is already testable on real sample extensions.

mv3migrate is not a promise of full automation. It is a narrow tool that is useful exactly where MV2 to MV3 migration usually slows down: common manifest edits, code-level API swaps, and transparent warnings for the hard parts.

Free path

Verified on simple-popup with manifest conversion, JS rewrites, HTML output, and `--version`.

Token unlock

Verified with signed license issuance, Ed25519 verification, and paid CLI execution.

Paid flows

Verified on batch runs, patch export, premium JSON, and DNR drafts for blocking, redirect, and header listeners.

Chrome smoke

The unpacked-extension smoke script exists and fails loudly on managed Chrome instead of faking success.

Advanced rewrites

Verified on executeScript and insertCSS calls that carry allFrames, world, origin, and injectImmediately options.

Evidence-rich DNR

Verified on multi-route webRequest fixtures with draft-rule evidence, redirect, block, and header mutation output.

Manifest-only cases

Verified on CSP and web_accessible_resources conversion, including the remote-hosted-code warning path.

Built for migration work

Everything the first migration pass needs.

The product is intentionally narrow: automate the common parts, surface the risky parts, and give the user a report they can trust.

Manifest conversion

Moves the obvious MV2 fields to MV3: browser_action, page_action, background scripts, host permissions, WAR, and CSP.

JS rewrite

Updates common API calls like browserAction, pageAction, executeScript, insertCSS, and getBackgroundPage, while preserving extra executeScript/insertCSS options when possible.

Risk scanner

Flags webRequestBlocking, eval, and non-trivial patterns that should not be silently “fixed”.

Readable output

Writes a JSON summary and an HTML report so a migration is easy to inspect, share, and review, including evidence-rich DNR drafts.

Fixture-first validation

Built around real sample extensions, not a toy input. The MVP already runs through free runs, token unlocks, batch mode, and DNR fixtures.

Local-first workflow

No SaaS dependency required to get value. Run it on a repo, mint a token by hand if needed, and keep moving.

Purchase and unlock

Buying is simple. The CLI stays local and offline.

There is no hosted account to sign into. The buyer emails us, we issue a signed token, and the CLI unlocks Pro features locally with a public key. That keeps the handoff explicit and avoids turning the product into SaaS.

Step 1

Buy Pro

Use the pricing email link and send the buyer details. The product stays one-time purchase and local-first.

Step 2

Receive a token

We issue a signed Ed25519 license token by email. It carries customer, plan, seat count, and expiry metadata.

Step 3

Run locally

The customer runs mv3migrate on a local extension folder and passes --license plus the public key to unlock Pro.

Step 4

Review output

The CLI writes the converted tree, HTML report, premium JSON, and patch file. The buyer then validates the result in Chrome.

Customer commands

$ mv3migrate ./my-extension --out ./my-extension-mv3 --report ./report.html

$ mv3migrate ./my-extension --out ./my-extension-mv3 --report ./report.html --emit-dnr --emit-patch --license "mv3migrate...." --license-public-key ./keys/mv3migrate-public.pem

Verified paths

The public story matches what we have already run.

This is not a theoretical migration tool. The current release has been exercised on real fixture trees, actual token issuance, and the paid command-line path that uses the token to unlock premium features.

free single-folder runs

signed token issuance

token verification and paid unlock

batch migration mode

patch export

DNR drafts for block, redirect, and header listeners

executeScript and insertCSS rewrites with extra options

evidence-rich DNR drafts

CSP and web_accessible_resources conversion

fixture-based regression tests

Chrome unpacked smoke script

auto-PR preparation script

6 public third-party MV2 repos verified

Third-party verification

We also ran the CLI on public MV2 repos that were not authored for this project.

Six public repositories passed the current runner. One additional sample was excluded because its manifest file is not valid JSON and the CLI intentionally rejects that input.

isaacherrera47/chrome-extension-test

repodevcode/Chrome-Extensions-Template--manifest-v2-

nikunjjoshi04/chrome_extension_hello_world/manifest_version_2

rohitsharmaj7/Chrome-Extensions/hello world

AshHeskes/eval-extension/client

iiteen/MYT

Excluded sample

yuvrajverma01/Instant_Profile_Access

How it works

A migration flow you can verify step by step.

Every output can be inspected locally. No hidden service, no opaque upload, no false claim that the hard parts are “done”.

Scan the extension

Walk the tree, find manifest.json, detect MV2-only APIs, and map risky files before any rewrite happens.

Rewrite the obvious parts

Convert the manifest, replace the straightforward API calls, and keep the rest of the code untouched.

Review the report

Open the HTML report, inspect the critical items, and decide whether the output is ready or needs manual work.

Install

Start from a folder, not a blank page.

The CLI is local-first. Point it at a repo, get a transformed output directory, and inspect the report before you decide what to keep or change.

If you buy Pro, the only extra inputs are the signed token and the public key. No account login, no hosted dashboard, and no code upload by default.

$ node ./src/cli.js ./my-extension --out ./my-extension-mv3

✓ manifest.json converted

✓ common JS API calls rewritten

! risk scan attached as HTML report

✓ output ready for load-unpacked validation

FAQ

The questions that decide whether this is worth using.

Who is this for?▾

Developers and maintainers who already have MV2 code and need a first-pass migration path instead of a blank template.

Does it solve every migration automatically?▾

No. It automates the common shape of the work and explicitly leaves ambiguous cases as warnings.

Why not just use the official converter?▾

The official tools help, but they do not complete the whole migration. This product is focused on the missing middle.

What can I verify locally?▾

Run the CLI on fixtures, inspect the transformed output, confirm the HTML report, test the license-token path on a local keypair, and load the output as an unpacked extension in Chrome.

How do I buy Pro and use it?▾

Click the pricing email link, receive a signed token by email, then run mv3migrate with --license and --license-public-key on your local extension folder.

EloLin ecosystem

One product, one public site, and the rest of the product graph stays connected.

mv3migrate-site is the public face for docs, issues, and product updates. The other sites stay linked so a user can move between tools without losing context.

EloLin