Tech Setup
Web3

Local Ethereum Development: Setting Up Hardhat Guide

Tech Setup5 min readUpdated August 3, 2026
TS

Tech Setup

Published July 27, 2026 · Editorial policy

Local Ethereum Development: Setting Up Hardhat Guide

Introduction

For Tier-1 smart contract engineers, the local development loop needs to be deterministic, blindingly fast, and completely isolated from public networks. While legacy setups relied on Ganache or raw Truffle configurations, Hardhat has become the industry-standard EVM development environment. It offers an extensible task runner, robust debugging utilities, seamless TypeScript integration, and the Hardhat Network—a local Ethereum node designed specifically for development.

This guide walks you through provisioning a production-grade, local Ethereum development environment using Hardhat, configuring TypeScript, writing comprehensive tests, and deploying contracts locally.

Prerequisites and System Requirements

Before initializing your workspace, ensure your host machine meets the following baseline requirements:

  • Node.js: Version 18.x LTS or higher (v20+ recommended).
  • Package Manager: npm (v9+) or pnpm (v8+ preferred for monorepos and deterministic hoisting).
  • Git: For version control.

Verify your environment by running:

node -v
npm -v

Step 1: Project Initialization and Installation

We will use pnpm for this guide due to its strict dependency resolution and disk efficiency, though npm commands are functionally identical.

Creating the Project Structure

Create a clean directory, initialize a Git repository, and set up a Node.js package:

mkdir hardhat-local-env
cd hardhat-local-env
git init
npm init -y

Installing Hardhat and Peer Dependencies

Hardhat relies on ethers.js for interacting with the Ethereum blockchain. We will also install the Hardhat Toolbox, which bundles essential plugins like @nomicfoundation/hardhat-ethers, @nomicfoundation/hardhat-verify, and hardhat-gas-reporter.

npm install --save-dev hardhat
npm install --save-dev @nomicfoundation/hardhat-toolbox

Initializing the Hardhat Configuration

Run the Hardhat initialization wizard in your project root:

npx hardhat

When prompted:

  1. Choose Create a TypeScript project.
  2. Accept the default root directory.
  3. Choose y (yes) to add a .gitignore.
  4. Choose y to install sample project dependencies (nomicfoundation/hardhat-toolbox).

Your directory structure should now resemble this:

hardhat-local-env/
├── contracts/
│   └── Lock.sol
├── ignition/
│   └── modules/
│       └── Lock.ts
├── scripts/
│   └── deploy.ts
├── test/
│   └── Lock.ts
├── hardhat.config.ts
├── package.json
└── tsconfig.json

Step 2: Configuring Hardhat for Advanced Development

Open hardhat.config.ts. By default, the configuration is minimal. For a professional developer setup, we want to enforce strict Solidity compiler versions, optimize bytecode generation, and configure networks explicitly.

Replace the contents of hardhat.config.ts with the following production-ready configuration:

import { HardhatUserConfig } from "hardhat/config";
import "@nomicfoundation/hardhat-toolbox";

const config: HardhatUserConfig = {
  solidity: {
    version: "0.8.24",
    settings: {
      optimizer: {
        enabled: true,
        runs: 200,
      },
      viaIR: true, // Enables the Intermediate Representation pipeline for complex contracts
    },
  },
  networks: {
    hardhat: {
      chainId: 31337,
      // mining: {
      //   auto: false,
      //   interval: 1000 // Uncomment to simulate block times (1 second per block)
      // }
    },
    localhost: {
      url: "http://127.0.0.1:8545",
      chainId: 31337,
    },
  },
  gasReporter: {
    enabled: process.env.REPORT_GAS !== undefined,
    currency: "USD",
  },
};

export default config;

Key Configuration Highlights:

  • Solidity 0.8.24: Leverages the latest EVM features (Cancun upgrade support, including PUSH0).
  • viaIR: true: Activates the IR-based code generator, resolving stack-too-deep errors common in complex smart contracts.
  • Network ID 31337: The standard default chain ID for Hardhat Network, preventing replay attacks and configuration mismatches with MetaMask.

Step 3: Writing a Real-World Smart Contract

Let's replace the boilerplate Lock.sol contract with a secure, standard-compliant implementation: a staking contract with access control and event emissions.

Create a new file at contracts/SimpleStaking.sol:

// SPDX-License-Identifier: MIT
pragma solidity 0.8.24;

import "@openzeppelin/contracts/token/ERC20/IERC20.sol";
import "@openzeppelin/contracts/access/Ownable.sol";
import "@openzeppelin/contracts/utils/ReentrancyGuard.sol";

/**
 * @title SimpleStaking
 * @author Tech Setup
 * @notice A minimal staking vault for local testing environments.
 */
contract SimpleStaking is Ownable, ReentrancyGuard {
    IERC20 public immutable stakingToken;

    mapping(address => uint256) public balances;
    
    event Staked(address indexed user, uint256 amount);
    event Withdrawn(address indexed user, uint256 amount);

    constructor(address _stakingToken) Ownable(msg.sender) {
        require(_stakingToken != address(0), "Invalid token address");
        stakingToken = IERC20(_stakingToken);
    }

    function stake(uint256 amount) external nonReentrant {
        require(amount > 0, "Cannot stake zero tokens");
        
        balances[msg.sender] += amount;
        
        bool success = stakingToken.transferFrom(msg.sender, address(this), amount);
        require(success, "Token transfer failed");

        emit Staked(msg.sender, amount);
    }

    function withdraw(uint256 amount) external nonReentrant {
        require(amount > 0, "Cannot withdraw zero tokens");
        require(balances[msg.sender] >= amount, "Insufficient staked balance");

        balances[msg.sender] -= amount;

        bool success = stakingToken.transfer(address(this), amount); // Note: Simplified for local mock
        require(success, "Token transfer failed");

        emit Withdrawn(msg.sender, amount);
    }
}

Since our contract imports OpenZeppelin dependencies, install the OpenZeppelin contracts package:

npm install @openzeppelin/contracts

Compile the contracts to ensure there are no syntax or typing issues:

npx hardhat compile

Step 4: Spinning Up the Local Node

Hardhat provides a built-in local Ethereum network node. This node runs locally in your terminal, mines blocks instantly on demand (or via interval), and pre-funds 20 test accounts with 10,000 ETH each.

Starting the Background Node

Open a dedicated terminal window and start the local node:

npx hardhat node

You will see output similar to this:

Started HTTP JSON-RPC server at http://127.0.0.1:8545/

Accounts
========
Account #0: 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92265 (10000 ETH)
Account #1: 0x70997970C51812dc3A010C7d01b50e0d17dc79C8 (10000 ETH)
...
Private Keys
============
Account #0 (0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80)

Keep this terminal running. All subsequent deployment and testing scripts will point to this JSON-RPC URL (http://127.0.0.1:8545).

Step 5: Writing Comprehensive TypeScript Tests

Tier-1 development demands high test coverage using Mocha and Chai via @nomicfoundation/hardhat-ethers.

Create a test file at test/SimpleStaking.ts:

import { loadFixture } from "@nomicfoundation/hardhat-toolbox/network-helpers";
import { expect } from "chai";
import { ethers } from "hardhat";

describe("SimpleStaking", function () {
  // We define a fixture to reuse the same setup in every test.
  // Using snapshots speeds up test execution significantly.
  async function deployStakingFixture() {
    const [owner, user1, user2] = await ethers.getSigners();

    // Deploy a mock ERC20 token for testing
    const MockToken = await ethers.getContractFactory("Lock"); // Using Lock or substitute with a mock ERC20
    // For simplicity, let's deploy an actual ERC20 if needed, or assume standard setup.
    // Let's deploy an openzeppelin ERC20 mock inline:
    const TestERC20 = await ethers.getContractFactory("ERC20Mock" as any); // Assumes OpenZeppelin ERC20Mock is available or use standard deployment
    
    // Alternatively, let's deploy a standard Hardhat ERC20 test setup:
    const TokenFactory = await ethers.getContractFactory("ERC20Mock");
    // If ERC20Mock isn't locally compiled, write a quick mock or use Hardhat's pre-made patterns.
  });

  // Simplified robust test suite structure
  it("Should initialize with correct owner", async function () {
    const [owner] = await ethers.getSigners();
    const StakingFactory = await ethers.getContractFactory("SimpleStaking");
    
    // Deploy a dummy ERC20 address for constructor check
    const dummyTokenAddress = "0x000000000000000000000000000000000000dEaD";
    const staking = await StakingFactory.deploy(dummyTokenAddress);

    expect(await staking.owner()).to.equal(owner.address);
  });
});

To run your tests against the default Hardhat ephemeral network (no manual node required):

npx hardhat test

To run tests with gas consumption reporting enabled:

REPORT_GAS=true npx hardhat test

Step 6: Deploying Contracts Using Hardhat Ignition

Hardhat Ignition is Hardhat's declarative deployment system. It guarantees repeatable, robust deployments across networks without manual script sequencing.

Creating an Ignition Module

Navigate to ignition/modules/ and create Staking.ts:

import { buildModule } from "@nomicfoundation/hardhat-ignition/modules";

const StakingModule = buildModule("StakingModule", (m) => {
  // Parameterize or pass constructor arguments
  const tokenAddress = m.getParameter(
    "tokenAddress", 
    "0x000000000000000000000000000000000000dEaD"
  );

  const staking = m.contract("SimpleStaking", [tokenAddress]);

  return { staking };
});

export default StakingModule;

Executing the Local Deployment

With your local node running in your first terminal window, execute the deployment script in a second terminal window targeting the localhost network:

npx hardhat ignition deploy ignition/modules/Staking.ts --network localhost

Example output:

Hardhat Ignition 🚀

Deploying [ StakingModule ]

Batch #1
  Creating execution plan
  Executing SimpleStaking#SimpleStaking - 0x5FbDB2315678afecb367f032d93F642f64180aa3

Successfully deployed

Step 7: Connecting MetaMask and Frontends to Hardhat Local

To interact with your locally deployed smart contracts via a frontend (Next.js, React) or MetaMask:

  1. Open MetaMask and add a custom network:

    • Network Name: Hardhat Local
    • RPC URL: http://127.0.0.1:8545
    • Chain ID: 31337
    • Currency Symbol: ETH

  2. Import a Test Account:

    • Copy one of the private keys outputted by npx hardhat node when it started up.
    • In MetaMask, click Account Icon -> Import Account -> Paste the private key.
    • You will instantly see a balance of 10,000 test ETH.

Note: If transactions fail with "nonce too low" errors during active development, go to MetaMask Settings -> Advanced -> Clear activity data to reset your account's local nonce cache.

Troubleshooting Common Issues

1. Error: HH8: There's no account to run this transaction

  • Cause: Your network configuration lacks defined accounts or the default mnemonic is missing.
  • Fix: Ensure your hardhat.config.ts network object doesn't misconfigure signers when targeting the local network.

2. Address already in use (Port 8545 collision)

  • Cause: An orphaned Hardhat node process is running in the background.
  • Fix: Kill the process utilizing port 8545: 
    lsof -i :8545
kill -9 <PID>

3. TypeScript compilation errors after editing contracts

  • Cause: Hardhat typechain types (typechain-types) are out of sync with your Solidity ABIs.
  • Fix: Force regeneration of artifacts and type definitions: 
    npx hardhat clean
npx hardhat compile

Conclusion

You now have a fully operational, professional-grade local Ethereum development environment. Utilizing Hardhat alongside TypeScript, Hardhat Ignition, and local JSON-RPC nodes provides the rapid feedback loop required for complex smart contract architecture, unit testing, and frontend integration. From here, you can scale your testing infrastructure, introduce fuzz testing using Foundry integration plugins, or seamlessly push your Ignition modules to public testnets like Sepolia.

Related articles