Node.js Ethereum dev environment from Nomic Foundation. Hardhat 3 ships an ESM/TypeScript-first config, the Node test runner, native viem support, and a plugin ecosystem (Ignition for declarative deploys, hardhat-toolbox-viem, hardhat-verify).
- 01TypeScript-first contract testing
- 02JavaScript/TS scripts and integrations
- 03declarative deployments with Hardhat Ignition
- 04complex multi-contract pipelines
- 05teams already using the JS/TS ecosystem
- pnpm add -D hardhat
- pnpm dlx hardhat --init
- pnpm add -D @nomicfoundation/hardhat-toolbox-viem
- pnpm add -D @nomicfoundation/hardhat-ignition @nomicfoundation/hardhat-verify
| Variable | Scope | Description |
|---|---|---|
| SEPOLIA_RPC_URL | Server | RPC URL for the Sepolia (or other) network referenced from `hardhat.config.ts`. |
| HARDHAT_PRIVATE_KEY | Server | Deployer private key referenced as `accounts: [process.env.HARDHAT_PRIVATE_KEY]`. Use Hardhat's encrypted keystore (`npx hardhat keystore`) for production secrets. |
| ETHERSCAN_API_KEY | Server | Etherscan (or v2-compatible) API key used by `hardhat-verify`. |
Use Hardhat 3 as the dev environment. Scaffold with `pnpm dlx hardhat --init` and pick the TypeScript + Node Test Runner + viem template. Import `hardhatToolboxViem` in `hardhat.config.ts` and write tests in `test/` using `node:test` plus `network.connect()` for viem clients. For deployments use Hardhat Ignition modules (`ignition/modules/Token.ts`) and run `npx hardhat ignition deploy ./ignition/modules/Token.ts --network sepolia`. Verify with `npx hardhat verify --network sepolia <address> <ctorArgs>`. Keep secrets out of `hardhat.config.ts` by using `npx hardhat keystore set <KEY>` instead of raw env vars.
- ⚑Hardhat 3 is ESM-first — older plugins built for Hardhat 2 (CJS) may not load. Check plugin compatibility (especially with viem v2 and Ignition) before upgrading existing projects.
- ⚑`hardhat-toolbox` (ethers) and `hardhat-toolbox-viem` are mutually exclusive — installing both confuses the runtime. Pick one client library per project.
- ⚑Hardhat Network's default chain ID is 31337 and forking from mainnet caches state per block — clearing the cache (`--fresh` or deleting `cache/hardhat-network-fork`) is required when forking a different block.
- ⚑`accounts: [process.env.PRIVATE_KEY]` will silently become `[undefined]` if the env var isn't loaded — Hardhat 3 throws clearer errors but older configs deploy from the zero address. Prefer the keystore.
- ⚑Gas reporting and coverage plugins (`hardhat-gas-reporter`, `solidity-coverage`) are slow on large suites; gate them behind `REPORT_GAS=true` rather than always-on.
- ⚑`hardhat-verify` v2 uses Etherscan's unified v2 API (single key for all chains) — old per-chain Etherscan keys still work but emit deprecation warnings.