Hardhat & TypeScript Setup

Hello! Welcome to the first lesson of Module 2: "Modern Development & Testing Toolchain."

Introduction

In Module 1, we built a solid conceptual foundation of how Ethereum works, covering the EVM, transaction lifecycle, gas fees, and the distinction between EOAs and Smart Contract Accounts. Now, it's time to transition from theory to practice and start building.

This module is all about the tools that enable professional smart contract development. As an experienced front-end developer, you're well-acquainted with the importance of a robust toolchain for compilation, testing, and deployment. The world of smart contracts is no different.

Today, we'll focus on setting up what is arguably the most popular development environment in the Ethereum ecosystem: Hardhat.

Learning Outcome: By the end of this lesson, you will be able to set up a Hardhat development environment with TypeScript configuration.

We will leverage your existing expertise with Node.js, npm, and TypeScript, focusing specifically on how these tools are integrated and configured within the Hardhat framework.

1. Prerequisites and What is Hardhat?

Hardhat is an Ethereum development environment that facilitates the entire smart contract lifecycle: compiling, running, testing, debugging, and deploying. It's built as a flexible and extensible task runner, with most of its functionality coming from plugins.

Before we begin, let's ensure you have the necessary software installed.

The core of a modern Hardhat setup is the @nomicfoundation/hardhat-toolbox plugin. Think of it as being similar to create-react-app or other starter kits; it bundles a curated set of essential plugins (like Ethers.js for blockchain interaction, Chai for testing, and TypeChain for TypeScript typings) so you don't have to configure them individually.

2. Initializing a TypeScript Project

Let's walk through the process of creating a new Hardhat project from scratch. The process involves initializing a standard Node.js project and then running the Hardhat initializer, which scaffolds the project structure for you.

The following video provides a quick visual walkthrough of this process.

Now, let's perform these steps ourselves.

Action: Follow these steps in your terminal:

1. Create a new directory for your project and navigate into it:

   mkdir my-hardhat-project
   cd my-hardhat-project
   

2. Initialize a Node.js project. The -y flag accepts all the defaults.

   npm init -y
   

3. Run the Hardhat initializer. This command will download Hardhat if needed and start the interactive setup guide.

   npx hardhat init
   

4. When prompted, make these selections:

   • What do you want to do? → Create a TypeScript project
   • Hardhat project root: → Accept the default (the current directory).
   • Do you want to add a .gitignore? → Yes
   • Do you want to install this project's dependencies with npm? → Yes

Hardhat will now create the necessary files and install dependencies, including hardhat, @nomicfoundation/hardhat-toolbox, typescript, and various @types packages.

3. Understanding the Project Structure

After the initialization completes, your project directory will have a structure designed for smart contract development.

Here is a summary of the key components:

• contracts/: This is where your Solidity source code (.sol files) lives. The sample project includes a Counter.sol.
• test/: This folder is for your test files. The sample project provides a Counter.ts, demonstrating how to write tests in TypeScript.
• ignition/: This folder contains deployment scripts using Hardhat Ignition, a modern, declarative deployment system. We'll explore this in a later module.
• hardhat.config.ts: This is the heart of your project's configuration. You define your Solidity compiler version, network settings (e.g., for testnets or mainnet), and plugins here.
• tsconfig.json: The standard TypeScript configuration file. Hardhat's initializer creates one with sensible defaults for a web3 project.

4. A Closer Look at the TypeScript Configuration

Since you chose a TypeScript project, Hardhat has pre-configured everything for a type-safe workflow. Let's examine the specifics.

Let's distill the most important points from that reading.

The hardhat.config.ts File

Your generated hardhat.config.ts will look something like this:

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

const config: HardhatUserConfig = {
  solidity: "0.8.24", // Or whichever version was latest
};

export default config;

The key advantages here, which will be familiar from your front-end work, are:

1. ESM Syntax: Using import/export instead of require/module.exports.
2. Type Safety: Importing the HardhatUserConfig type from hardhat/config allows your code editor to provide autocompletion and validation for the configuration object. This prevents typos and configuration errors.

Type-Safe Contract Interactions with TypeChain

This is the most significant benefit of using TypeScript with Hardhat. The @nomicfoundation/hardhat-toolbox automatically integrates a tool called TypeChain.

Here's how it works:

1. When you compile your Solidity contracts (e.g., by running npx hardhat compile), Hardhat generates the ABI (Application Binary Interface).
2. TypeChain then reads these ABIs and automatically generates TypeScript definition files (.d.ts).
3. These definitions provide full type information for your contracts. When you instantiate a contract in your tests or scripts, TypeScript will know all of its functions, their arguments, their return types, and all of its events.

This eliminates a common source of bugs and dramatically improves the developer experience with features like autocompletion for contract methods.

5. Verifying Your Setup

The initialized project comes with a sample contract (Counter.sol) and a corresponding test file (test/Counter.ts). Running this test is the best way to confirm that your entire toolchain—compilation, test execution, and TypeScript integration—is working correctly.

In your terminal, run the test command:

npx hardhat test

You should see output indicating that the contract was compiled and that the tests passed.

A final tip for maintaining a robust project is to use the --typecheck flag. By default, Hardhat does not run the TypeScript compiler during tasks for performance reasons. You can force it to do so with this flag.

npx hardhat test --typecheck

This is highly recommended for your Continuous Integration (CI) pipeline to ensure type safety before merging code.

Conclusion

Congratulations! You have successfully set up a professional, type-safe Hardhat development environment. This setup will be the foundation for all the smart contracts we build, test, and deploy throughout this course.

Key Takeaways:

• Hardhat is a comprehensive development environment for Ethereum.
• npx hardhat init is the command to bootstrap a new project, with an option for a pre-configured TypeScript setup.
• The @nomicfoundation/hardhat-toolbox package bundles essential plugins for a modern workflow.
• Using TypeScript provides type safety for your configuration (hardhat.config.ts) and, most importantly, for your smart contract interactions via TypeChain, which auto-generates types from your contract ABIs.
• You can verify your setup by running the default tests with npx hardhat test.

Next Steps:

While Hardhat is the most established tool, a newer, high-performance alternative called Foundry has gained significant popularity. In the next lesson, we will set up a Foundry project. Afterward, we will compare the philosophies and workflows of Hardhat (using TypeScript for tests) and Foundry (using Solidity for tests) to help you decide which tool best fits your style.