Hardhat Tutorial | Complete Guide to Ethereum Smart Contract Development

What is Hardhat?

Hardhat is a local development environment for Ethereum software. It helps developers compile contracts, run tests, debug smart contracts, deploy to networks and automate common blockchain development tasks.

Smart contract workflow

Compile, test, deploy and debug Solidity contracts from one development environment.

Tasks and plugins

Hardhat workflows are built around reusable commands and extensible plugins.

Local blockchain

Hardhat Network lets you test contracts locally before moving to public testnets.

Team-friendly tooling

Hardhat works well with JavaScript, TypeScript, Ethers, testing tools and deployment scripts.

Example Hardhat task

npx hardhat compile

Prerequisites

Use Windows PowerShell for this tutorial. Install the tools below before creating the project.

Node.js and npm

JavaScript runtime and package manager used to install Hardhat and plugins.

Alchemy Account

Blockchain developer platform used for testnet and network API access.

VS Code

Recommended editor for JavaScript, TypeScript and Solidity projects.

MetaMask

Wallet used for testnet accounts and transaction signing.

Create Project Folders and Install Hardhat

1. Create separate folders

PowerShell

mkdir Project_JScript
mkdir Project_TSCript

2. Install Hardhat locally

Install Hardhat

npm install --save-dev hardhat

3. Initialize the project

Start Hardhat project setup

npx hardhat

The initialization menu lets you create a JavaScript project, TypeScript project or empty configuration file.

Tip: If you need the project setup menu again, delete hardhat.config.js and run npx hardhat again.

Project Structure

JavaScript Project

Uses hardhat.config.js, JavaScript deployment scripts and standard test files.

TypeScript Project

Uses hardhat.config.ts, tsconfig.json and generated type files.

JavaScript project folders

Typical JavaScript structure

contracts/
scripts/
test/
.gitignore
hardhat.config.js
package.json
README.md

TypeScript project folders

Typical TypeScript structure

contracts/
scripts/
test/
typechain-types/
hardhat.config.ts
tsconfig.json
package.json

Configuration Files

JavaScript configuration

hardhat.config.js

require("@nomicfoundation/hardhat-toolbox");

module.exports = {
  solidity: "0.8.17",
};

TypeScript configuration

hardhat.config.ts

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

const config: HardhatUserConfig = {
  solidity: "0.8.17",
};

export default config;

Compiling Smart Contracts

Compilation checks your Solidity code and creates artifacts required for deployment and interaction.

Compile command

npx hardhat compile

Expected output

Successful compile result

Downloading compiler 0.8.17
Compiled 1 Solidity file successfully

Common compile error

Fix missing toolbox plugin

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

Essential Dependencies and Testing

Install these modules if you want a fuller smart contract testing and reporting setup.

Recommended development dependencies

npm install --save-dev @nomicfoundation/hardhat-toolbox
npm install --save-dev @typechain/hardhat --legacy-peer-deps
npm install --save-dev hardhat-gas-reporter --legacy-peer-deps
npm install --save-dev solidity-coverage --legacy-peer-deps

Testing commands

Run tests

npx hardhat test
npx hardhat test test/my-tests.ts

Setting Up Local Hardhat Network

Open a new terminal and start a local Hardhat blockchain for development and testing.

Start local network

npx hardhat node

20 test accounts

Hardhat provides funded local accounts for safe testing.

10,000 ETH each

Local test ETH has no real-world value and is only for development.

localhost:8545

The local blockchain runs on your machine.

Automatic mining

Transactions are mined automatically for quick feedback.

Deploy locally

JavaScript deployment

npx hardhat run --network localhost scripts/deploy.js

TypeScript deployment

npx hardhat run --network localhost scripts/deploy.ts

Testnet Configuration

For public testnet deployment, use an API provider, a test wallet and free testnet ETH. Sepolia is a better current example than Goerli for new tutorials.

Sepolia configuration example

hardhat.config.js

require("@nomicfoundation/hardhat-toolbox");

const ALCHEMY_API_KEY = "YOUR_SEPOLIA_KEY";
const SEPOLIA_PRIVATE_KEY = "YOUR_PRIVATE_KEY";

module.exports = {
  solidity: "0.8.18",
  networks: {
    sepolia: {
      url: `https://eth-sepolia.g.alchemy.com/v2/${ALCHEMY_API_KEY}`,
      accounts: [SEPOLIA_PRIVATE_KEY]
    }
  }
};

Deployment commands

Deploy to testnet

npx hardhat run scripts/deploy.js --network sepolia
npx hardhat run scripts/deploy.ts --network sepolia

Security reminder: Use a separate test wallet only. Never paste a real funded wallet private key into code, screenshots, GitHub, email or public files. Prefer environment variables for keys.

OpenZeppelin Integration

OpenZeppelin provides secure, reusable smart contract libraries for tokens and common contract patterns.

Install OpenZeppelin contracts

npm install @openzeppelin/contracts

Sample NFT contract structure

MyNFT.sol example

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

import "@openzeppelin/contracts/token/ERC721/ERC721.sol";
import "@openzeppelin/contracts/access/Ownable.sol";

contract MyNFT is ERC721, Ownable {
    uint256 private tokenId;

    constructor() ERC721("MyNFT", "NFT") {}

    function mintNFT(address recipient) public onlyOwner returns (uint256) {
        tokenId++;
        _mint(recipient, tokenId);
        return tokenId;
    }
}

Common Issues and Solutions

Insufficient funds error

Reduce the locked amount in the deployment script when the account does not have enough test ETH.

Missing menu after installation

Delete generated scripts/contracts if needed, remove hardhat.config.js, then run setup again.

Deployment debugging

Use stack traces to diagnose testnet deployment failures.

Toolbox missing

Install @nomicfoundation/hardhat-toolbox when the module is not found.

Debug deployment command

npx hardhat run scripts/deploy.ts --network sepolia --show-stack-traces

Additional Resources

Hardhat Documentation

Official documentation for setup, testing, debugging, plugins and deployment.

Alchemy

Blockchain infrastructure and API platform for testnet and production deployments.

Etherscan

Contract verification and transaction exploration.

MetaMask

Wallet and Web3 gateway for Ethereum users and developers.

Congratulations!

You have learned the key parts of the Hardhat development workflow.

Set up Hardhat

Created a project and installed the core development tools.

Compile and test

Compiled Solidity contracts and ran Hardhat tests.

Deploy locally

Started a local blockchain and deployed to localhost.

Prepare for testnets

Configured Sepolia and learned safe deployment practices.

Development flow recap

Create Hardhat project

↓

Write Solidity contract

↓

Compile and test

↓

Deploy locally

↓

Deploy to Sepolia when ready