Getting started with Hardhat 3

Hardhat is a flexible and extensible development environment for Ethereum software. It helps you write, test, debug, and deploy your smart contracts with ease, whether you’re building a simple prototype or a complex production system.

This guide will walk you through installing our recommended setup, but since most of Hardhat’s functionality comes from plugins, you’re free to customize it or choose a completely different path.

Prerequisites

Node.js v22 or later
A package manager like npm, pnpm, or yarn (we strongly recommend pnpm)
A text editor (we recommend VS Code with our Official Hardhat extension)

Installation

First, create a new directory for your project:

mkdir hardhat-example
cd hardhat-example

Once that’s done, initialize your Hardhat project by running:

npx hardhat --init

pnpm dlx hardhat --init

yarn dlx hardhat --init

This command will prompt you with a few configuration options. You can accept the default answers to quickly create a working setup.

Using the defaults will initialize the project in the current directory and automatically install all required dependencies.

After the setup completes, you’ll have a fully working Hardhat 3 project. To verify everything’s set up correctly, run:

npx hardhat --help

pnpm hardhat --help

yarn hardhat --help

To try out a complete test run of your project, run:

npx hardhat test

pnpm hardhat test

yarn hardhat test

Project structure

The Hardhat project initialization from the previous section creates the following file structure:

Directoryhardhat-example
- package.json
- hardhat.config.ts
- Directorycontracts
  - Counter.sol
  - Counter.t.sol
- Directorytest
  - Counter.ts
- Directoryignition
  - Directorymodules
    Counter.ts
- Directoryscripts
  - send-op-tx.ts

Here’s what each file and directory does:

package.json: Your npm package file where Hardhat and its plugins are installed.
hardhat.config.ts: Your project’s main configuration file. It defines the Solidity compiler version, network configurations, plugins, and tasks.
contracts: Contains your Solidity contracts. You can also include Solidity test files here using the .t.sol extension.
test: Contains TypeScript and Solidity tests. Solidity test files in this folder can use either .sol or .t.sol.
ignition: Contains Hardhat Ignition deployment modules that describe how to deploy your contracts. Learn more here.
scripts: Contains custom scripts that automate parts of your workflow. Scripts have full access to Hardhat’s runtime and can use plugins, connect to networks, and deploy contracts.

You can learn more about what’s included in your sample project by reading the hardhat-toolbox-viem documentation, which is the recommended setup you’re using.

Learn more

To learn more about Hardhat, we recommend reading the tutorial next.

Once you’ve finished the tutorial, or if you prefer smaller focused guides, check out:

Join our Hardhat 3 Telegram group to share feedback and stay updated on new releases.