When to Apply
- Starting new Hardhat 3 projects.
- Migrating from v2 to v3.
- Testing Solidity contracts with Foundry-compatible tests.
- Deploying with Hardhat Ignition.
- Building multichain applications.
Requirements
| Requirement | Value |
|---|---|
| Node.js | v22.10 or newer |
| Module system | ESM — set "type": "module" in package.json |
| Init command | npx hardhat --init |
| Config entry | defineConfig from hardhat/config |
Configuration
Organize setup with solidity, networks, and plugins keys. Use configVariable("KEY") for secrets to keep them out of code. Plugins MUST be listed explicitly — side-effect imports from v2 no longer work.
Network type |
Use for |
|---|---|
edr-simulated |
Local in-process testing |
http |
Remote RPC connections |
chainType accepts "l1", "op", or "generic". Build profiles allow per-environment settings (e.g., enabling the optimizer for production).
import { defineConfig, configVariable } from "hardhat/config";
import { hardhatIgnition } from "@nomicfoundation/hardhat-ignition";
export default defineConfig({
solidity: "0.8.28",
plugins: [hardhatIgnition],
networks: {
hardhat: { type: "edr-simulated" },
mainnet: { type: "http", url: configVariable("MAINNET_RPC_URL") },
},
});
Testing
| Test type | Runner | Notes |
|---|---|---|
Solidity (.t.sol) |
Rust-powered | Inherits forge-std/Test.sol; full vm cheatcodes; fuzzing built-in |
| TypeScript | Node test runner + Viem, or Mocha + Ethers | Access network helpers via the networkHelpers property |
| Command | Runs |
|---|---|
npx hardhat test |
All tests |
npx hardhat test solidity |
Solidity tests only |
--coverage |
Coverage data |
--gas-stats |
Gas usage data |
Deployment (Ignition)
Hardhat Ignition is the primary deployment framework: declarative modules via buildModule, automatic transaction parallelization, and automatic resume of failed deployments.
- Deploy:
npx hardhat ignition deploy ignition/modules/MyModule.ts --network <network> - Verify:
@nomicfoundation/hardhat-verifyplugin
Multichain Support
Hardhat 3 simulates multiple chains at once. Connect per-network with const mainnet = await network.connect("mainnet"). Fork several chains concurrently for complex cross-chain testing.
Debugging
| Tool | Purpose |
|---|---|
console.log (hardhat/console.sol) |
Print debugging inside contracts |
Verbosity flags on the test command |
Increase trace detail |
| EDR stack traces | Detailed failure traces |
Migration from v2
| v2 | v3 |
|---|---|
| CommonJS | ESM ("type": "module") |
| Node.js < 22 | Node.js v22.10+ |
module.exports |
defineConfig |
| Side-effect plugin imports | Explicit plugins array |
| Ethers v5 | Ethers v6 or Viem |
| Single network object | Multichain NetworkManager |
| v2 plugins | v3-specific plugin versions |
Essential plugins: hardhat-verify, hardhat-ignition, hardhat-keystore.
Enhanced with MCP
When the solidity-agent-toolkit is available:
compile_contract: Build contracts and get artifacts.run_tests: Execute the test suite.gas_snapshot: Get gas reports.dry_run_deploy: Simulate deployments.run_slither,run_aderyn: Perform security analysis.
References
See the Hardhat 3 Cheatsheet for examples.