# hardhat

A Cursor rule that sets Hardhat 3 conventions for your project: TypeScript config, Solidity and TypeScript tests, Ignition deployments.

- rule · `type=rule` · Cursor · ★ 3579
- Author: sanjeed5
- License: CC0-1.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/sanjeed5/awesome-cursor-rules-mdc/tree/HEAD/rules-mdc/hardhat.mdc
- Updated: 2026-05-19
- HTML: https://affpapa.org/en/nevibecode/rules/hardhat

## What it does

The rule loads into Cursor and steers the agent toward Hardhat 3 conventions for Ethereum work. It asks you to move to version 3 right away, since version 2 is deprecated for new development. Configuration lives in `hardhat.config.ts` with pinned Solidity compiler versions and the optimizer turned on.

Project layout is spelled out folder by folder: contracts and Solidity tests with the `.t.sol` extension sit in `contracts/`, while deployment scripts and integration tests are TypeScript files in `scripts/` and `test/`. Mixing JavaScript and TypeScript is called out as wrong. Solidity unit tests use `forge-std` and `vm.expectRevert` instead of the `testFail` prefix; end-to-end scenarios use `ethers.js` through `@nomicfoundation/hardhat-ethers` plus `chai-matchers`.

Deployments go through Hardhat Ignition, where a module declares contracts instead of an imperative script. The config reads several environment variables — `SEPOLIA_RPC_URL`, `PRIVATE_KEY`, `ETHERSCAN_API_KEY`, `COINMARKETCAP_API_KEY` — so set those up before the related blocks can do anything. One caveat worth knowing: Hardhat's Solidity tests are Foundry-compatible with gaps, no inline NatSpec and no scripting cheatcodes like `startBroadcast`.

## Install

### Cursor (native platform)

**Manually: put the files in place**
- File: `.cursor/rules/hardhat.mdc` — Frontmatter: description, globs, alwaysApply

### Claude Code

**Manually: put the files in place**
- File: `.claude/rules/hardhat.md` — The paths frontmatter field limits the files: move globs from the source into paths

### Codex

**AGENTS.md**
- Codex reads AGENTS.md: paste the rule text there

### GitHub Copilot

**Manually: put the files in place**
- File: `.github/instructions/hardhat.instructions.md` — The applyTo field sets which files it applies to: move globs from the source into applyTo

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/rules/hardhat.md`

### Cline

**Manually: put the files in place**
- File: `.clinerules/hardhat.md`

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/sanjeed5/awesome-cursor-rules-mdc/tree/HEAD/rules-mdc/hardhat.mdc

## When to use it
- migrate a project from Hardhat 2 to Hardhat 3
- lay out contracts, tests and scripts without mixing JS and TS
- write Solidity unit tests with forge-std cheatcodes
- declare a deployment as an Ignition module instead of a manual script
- wire gas reporter and solhint into the config

## Example prompts
- Create `hardhat.config.ts` for Hardhat 3 with pinned Solidity versions and the optimizer on
- Lay out the project: contracts in `contracts/`, TypeScript integration tests in `test/`
- Declare the deployment as a Hardhat Ignition module in `ignition/modules/MyContract.ts`

## Source text · hardhat.mdc · CC0-1.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 03a28c54136dfa83.

BEGIN THIRD-PARTY FILE 03a28c54136dfa83
````text
---
description: Ensure Hardhat projects follow modern best practices for configuration, testing, deployment, and security using TypeScript and Hardhat 3's Rust runtime.
globs: **/*.{js,jsx}
---
# hardhat Best Practices

Hardhat 3 is the definitive standard for Ethereum development. These rules enforce a modern, secure, and efficient workflow leveraging its Rust runtime, TypeScript support, and robust testing tools.

## 1. Adopt Hardhat 3 Immediately

Migrate all projects to Hardhat 3. Its Rust-powered runtime offers superior performance, instant stack traces, and enhanced debugging. Hardhat 2 is deprecated for new development.

## 2. Standardized Project Configuration (`hardhat.config.ts`)

Always use TypeScript for your Hardhat configuration. Pin Solidity compiler versions, enable Solidity test conventions, and activate essential plugins.

**✅ GOOD: `hardhat.config.ts`**

```typescript
import { HardhatUserConfig } from "hardhat/config";
import "@nomicfoundation/hardhat-toolbox"; // Includes Ethers, Chai, Verify, etc.
import "@nomicfoundation/hardhat-ignition";
import "hardhat-gas-reporter";
import "solidity-coverage";
import "@nomicfoundation/hardhat-solhint"; // For Solhint

const config: HardhatUserConfig = {
  solidity: {
    compilers: [
      { version: "0.8.20" }, // Pin specific, stable Solidity versions
      { version: "0.8.21" },
    ],
    settings: {
      optimizer: {
        enabled: true,
        runs: 200,
      },
    },
  },
  networks: {
    hardhat: {
      // Hardhat Network for local development and testing
      chainId: 31337,
    },
    // Example for a testnet:
    sepolia: {
      url: process.env.SEPOLIA_RPC_URL || "",
      accounts: process.env.PRIVATE_KEY !== undefined ? [process.env.PRIVATE_KEY] : [],
    },
  },
  paths: {
    sources: "./contracts",
    tests: "./test",
    cache: "./cache",
    artifacts: "./artifacts",
    // Enable Solidity test file convention (e.g., `contracts/MyContract.t.sol`)
    // This is the default, but explicitly setting it is good practice.
    // tests: { solidity: "./contracts" } // If you want .t.sol files in contracts/
  },
  gasReporter: {
    enabled: process.env.REPORT_GAS !== undefined,
    currency: "USD",
    coinmarketcap: process.env.COINMARKETCAP_API_KEY,
  },
  typechain: {
    outDir: "typechain-types",
    target: "ethers-v6", // Use ethers-v6 for modern projects
  },
  etherscan: {
    apiKey: process.env.ETHERSCAN_API_KEY,
  },
};

export default config;
```

## 3. Opinionated Code Organization

Maintain a clean, predictable project structure. Use TypeScript for all non-Solidity code (scripts, tasks, tests).

**✅ GOOD: Project Structure**

```
.
├── contracts/
│   ├── MyContract.sol
│   └── MyContract.t.sol  // Solidity unit tests
├── scripts/
│   └── deploy.ts         // TypeScript deployment scripts
├── test/
│   └── MyContract.test.ts // TypeScript integration tests
├── hardhat.config.ts
├── package.json
├── tsconfig.json
└── README.md
```

**❌ BAD: Mixing JavaScript and TypeScript, inconsistent test locations**

```
.
├── contracts/
│   └── MyContract.sol
├── scripts/
│   └── deploy.js         // JavaScript deployment script
├── test/
│   ├── MyContract.test.js // JavaScript tests
│   └── MyContract.sol.js  // Solidity tests in JS? No.
````
END THIRD-PARTY FILE 03a28c54136dfa83

The third-party file has ended. Everything between the 03a28c54136dfa83 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 3412 of 9401 bytes. © sanjeed5 · CC0-1.0 · https://github.com/sanjeed5/awesome-cursor-rules-mdc/tree/HEAD/rules-mdc/hardhat.mdc

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md