Hardhat 3 is now stable

Hardhat 3 shipped as a beta on August 2025, with a major overhaul: Solidity tests as first-class, multichain support, a performant Rust-powered runtime via EDR, a revamped build system, and Hardhat Ignition for deployments. Hardhat is more than ready for production use for any kind of modern Solidity project. TypeScript tested, Solidity tested, fuzzed — or all of the above! See below what landed across the five releases that led to the stable release.

The shape of the stable release

The cycle since 3.0.0 beta has been about turning an ambitious rewrite into something teams can confidently standardize on. A few directional themes stand out:

• Improved performance. We worked on optimizing the bootstrap time, the build system, networking stack, and solidity tests, and are happy with the results, plus we’re working on further optimizations which will land in the near future.
• AI-ready out of the box. Templates ship with AGENTS.md, CLAUDE.md, and skills so AI coding tools understand a fresh Hardhat 3 project from the first prompt.
• A first-class testing story. Solidity and JS/TS tests share output, tracing, and coverage tooling, with new capabilities — gas snapshots, EIP-712 cheatcodes, inline config, HTML coverage — that close the gap with what Foundry users expect.
• Ready for migrating from foundry. Hardhat 3 now covers the majority of foundry’s functionality (including Solidity tests, fuzzing, and invariant testing), plus a lot more, and there’s a migration guide for those ready to make the switch.
• A rigorous bug fixing effort. We fixed issues that came from beta test users, major users starting their migration process, and preemptive internal migrations of major ecosystem repositories intended to surface bugs that would’ve come up later.
• Decreased number of dependencies. We’re continuously vendoring and reimplementing external dependencies internally to reduce the amount of transitive packages, leading to a leaner install and increased security.
• A mature network and execution layer. A cleaner network API, JSON-RPC behavior aligned with the rest of the ecosystem, and an EDR runtime that's kept current with the L1 and OP-Stack hardforks teams actually deploy to.
• A faster, smaller, more reproducible build system. Contracts and Solidity tests compile together by default, artifacts shrank meaningfully, and production builds now record enough metadata to be reproduced later.
• Better gas insight. Gas reporting moved from a debug aid to something you can wire into CI: aggregate stats, JSON export, and proxy-aware attribution.
• A plugin ecosystem that's caught up. Foundry interop, multi-provider verification (Etherscan, Blockscout, Sourcify), Hardhat Ignition, and Ledger all work on HH3 out of the box.

Companion plugin releases

A few plugins were updated or newly released alongside the H3 stable push.

• @nomicfoundation/hardhat-foundry@3.0.0 The HH3 port of the original plugin. Reads forge config, syncs sources/cache paths, and automatically feeds Foundry-generated remappings (including npm-installed ones) into Hardhat's compilation, closing the remappings UX gap tracked in issues #6508 and #4812.
• @nomicfoundation/hardhat-verify v3 exposes etherscan, blockscout, and sourcify as first-class providers in verifyContract; running verify with no subtask hits all three. Blockscout originally landed via issue #5224 and was carried into the H3 3.x line.
• @nomicfoundation/hardhat-ignition honors the same multi-provider flow through -verify on the deploy module: Sourcify is on by default and Blockscout works without an API key.
• @nomicfoundation/hardhat-ledger ported to Hardhat 3 (issues #5646, #6983) — uses the new network/provider API and is configured through ledgerAccounts in hardhat.config.ts.

Our gratitude to OpenZeppelin and 1inch teams

The contracts and upgrades teams at OpenZeppelin have collaborated very closely with us throughout this process, and the team at 1inch have been providing very valuable feedback as they migrate their projects to Hardhat 3, and we’re beyond grateful for all their input and feedback 🙏

Hardhat 3 is now stable, performant, and ready for prime time.

Check it out!

The path towards stability

3.1.* — December 2025

The first follow-up after the beta launch focused on EVM currency and test ergonomics.

• Unified test output between Solidity tests and the Node.js test runner — running multiple test tasks now produces merged summaries instead of separate ones.
• Default L1 hardfork bumped to Osaka; default OP stack hardfork bumped to Isthmus, with corrected post-Osaka transaction gas limits.
• HTML coverage report . --coverage now produces an HTML report at coverage/html/index.html in addition to the existing Markdown and LCOV outputs.
• Gas snapshots in Solidity tests added function-level gas snapshots and snapshot cheatcodes for Solidity tests, exposed through new --snapshot and --snapshot-check CLI flags.

3.2.0 — March 2026

A smaller release built around the new gas-stats workflow and a few correctness fixes.

• Improvements and stabilization of gas statistics. A new --gas-stats-json <path> option that writes gas usage to JSON for tooling/CI consumption. Deployment gas stats are now aggregated (min/avg/median/max/count) instead of only the last deployment cost and size, and multiple test runners are reported in a single consolidated table.
• network.createServer got a clearer non-generic chainTypes signature and a guard against http network configs.
• Internal dependency-vendoring workspace. A new @nomicfoundation/hardhat-vendored package was added as a home for small utilities that used to come from external npm packages. This sets up the lighter dependency footprint that lands in 3.5.0.

3.3.0 — March 2026

A performance-focused release with two additional notable features.

• Execution tracing for JS/TS integration tests via --verbosity / v, vv, etc. — previously trace output was Solidity-tests-only.
• Per-test inline configuration for Solidity tests (matching the inline-config workflow Foundry users expect).
• Plugin extensibility: a new ConfigHooks#validateResolvedConfig hook and HardhatConfigValidationError type, plus SolidityHooks#downloadCompilers and SolidityHooks#getCompiler so plugins can register custom Solidity compiler types.
• EDR network initialization performance optimizations

3.4.0 — April 2026

The largest release in the cycle and explicitly billed as "preparation of the first stable version of Hardhat 3." Several user- and plugin-facing migrations live here.

• New stabilized NetworkManager API. network.connect() is deprecated in favor of network.create() and network.getOrCreate(), which more clearly describe their semantics. The old call still works for now.
• Unified compilation of contracts and Solidity tests. Tests and contracts now build in a single pass, producing faster compiles and smaller artifacts. Projects that need the old isolated behavior can opt in with splitTestsCompilation: true in the solidity config. There's a detailed plugin migration guide covering scope rules, getRootFilePaths, getArtifactsDirectory, --no-tests / --no-contracts semantics, and the onCleanUpArtifacts hook.
• Smaller artifacts/ output by changing the default solc outputSelection — in some projects around 50% smaller.
• toolVersionsInBuildInfo setting, on by default in the production build profile, records the Hardhat version in BuildInfo files so production builds are easier to reproduce.
• JSON-RPC revert errors now use code 3 for simulated networks and hardhat node, aligning with the rest of the ecosystem (viem/ethers preserve error causes correctly).
• Proxy chains in --gas-stats: gas is attributed to the implementation contract reached through the proxy (e.g. Vault via Proxy), instead of being lumped under the proxy.

3.5.0 — May 2026

The most recent release; this is effectively the candidate for what becomes Hardhat 3 stable.

• Lighter dependency footprint. chalk and debug — two long-standing runtime dependencies — were removed in favor of the vendored equivalents in @nomicfoundation/hardhat-vendored, leaving a fresh Hardhat 3 project with a noticeably smaller install tree.
• EIP-712 cheatcodes in Solidity Test.
• Non-interactive project init: npx hardhat --init --template <template-name>, with -init --templates to list available templates.
• TypeScript 6 as the default in templates for new projects.
• Coverage improvements: respect user allowUnlimitedContractSize, disable transaction gas cap and block gas limit under --coverage, fix coverage instrumentation interfering with single-call vm.prank, add instrumentation support for Solidity 0.8.35.

3.6.0 stable — May, 2026

A focused release built around a Solidity-hooks overhaul and the final piece of agent-ready scaffolding for the stable launch.

• AI coding agent enhancements: Projects created with --init now ship with AGENTS.md and CLAUDE.md files plus a .claude/commands/ directory, providing ready-made context for agentic coding tools (Claude Code, Cursor, Aider, etc.). The Hardhat repo itself ships the same files at its root. These can be added to any HH3 project for better support.
• Solidity hooks overhaul (PR #8327). Two new hooks were added — processArtifactsAfterSuccessfulBuild (which receives a new exported ResolvedBuildOptions type) and getCompilationJobErrors, which lets plugins process compiler output errors before they reach the user. A long list of older hooks was deprecated and will be removed in a future release: getCompiler, onCleanUpArtifacts, preprocessProjectFileBeforeBuilding, preprocessSolcInputBeforeBuilding, readSourceFile, invokeSolc, and readNpmPackageRemappings. The reshuffle gives Hardhat more room to optimize the build pipeline without breaking plugins, and is positioned as the hook surface Hardhat 3 stable will commit to.
• cleanupArtifacts is now a build option. SolidityBuildSystem#build accepts a new cleanupArtifacts flag; when set, the build system deletes orphan artifacts and unreachable build-info files for the scope after a successful build. cleanupArtifacts itself also now returns the list of artifact paths remaining after the cleanup.
• Positional arguments accept value-less variants. STRING_WITHOUT_DEFAULT and FILE_WITHOUT_DEFAULT are now valid as positional arguments (PR #8335).