hh3-migrate

Migrate a Hardhat v2 project to Hardhat v3.

It rewrites your config and task surface, then compiles both trees and diffs bytecode, ABI, and storage layout so you can see whether the rewrite changed any contract output.

Install

Requires Node 22 or newer and a Hardhat v2 project.

npm i -D hh3-migrate

Run

Dry-run from the project root. Reports what would change, writes nothing:

npx hh3-migrate ./my-project

Apply the rewrites in place:

npx hh3-migrate ./my-project --write

Pick a single rule, or skip one, with --only and --skip (both repeatable):

npx hh3-migrate ./my-project --only network-entry-add-type
npx hh3-migrate ./my-project --skip tsconfig-module-node20 --write

In CI, pipe the JSON report to stdout:

npx hh3-migrate ./my-project --report-json -

What it does

v0.1 ships six core rules covering the config shape, network entries, and task surface:

• module.exports = { ... } becomes export default defineConfig({ ... })
• Injects import { defineConfig } from "hardhat/config" when the config rule fires
• Bumps tsconfig.compilerOptions.module to "node20", package.json#type to "module", engines.node to >=22
• Adds the mandatory type and chainType keys to every network entry
• subtask("foo", ...) becomes overrideTask(["foo"], ...)
• extendConfig, extendEnvironment, extendProvider become hookHandlers factories

After the rewrite (and only with --write), hh3-migrate runs the validation gate. It compiles v2 in your tree, runs your package manager install against the rewritten manifest, compiles v3, and diffs bytecode, ABI, and storage layout. Any diff exits with code 2 so CI fails loudly. --no-validate skips the gate.

What it does not do

• Plugin-aware rewrites (toolbox, verify, network-helpers, hardhat-deploy) are deferred to v0.2.
• No behavioral test runs. The validator stops at artifact diffs.
• No fixpoint loop. One ordered pass, and rule order is the contract.
• hardhat-deploy v1 will be flagged in v0.2, never rewritten.

Exit codes

| Code | Meaning | |---|---| | 0 | Clean. Nothing to do or nothing changed. | | 1 | Changes applied with --write, or changes pending in dry-run. | | 2 | Validation diff. Compile-both-sides found drift. | | 3 | Config or input error. | | 4 | Internal failure. |

Docs

• Topic-specific reference (architecture, rules, validation, CLI, releasing): docs/README.md
• Full v0.1 spec (architecture, slice list, future considerations): SPEC.md
• Per-folder design docs: src/
• Worked examples: examples/README.md

License

MIT. See LICENSE.