Foundry compatibility

Hardhat 3 is designed to be compatible with Foundry. Read this section to learn more about how to use Hardhat 3 with contracts built with Foundry.

Solidity build process compatibility

You can use Hardhat 3 to build contracts and tests created with Foundry.

Configuration

You may want to configure your Hardhat project to make it easier to work with Foundry, like setting src/ as the main source directory. Read the configuration reference for more information.

Remappings

Hardhat 3 supports remappings.txt files by default. It automatically loads all the remappings.txt files in your project, and in the npm packages that your project depends on. Hardhat 3’s remappings support is more advanced, and limits the scope of each remapping to the directory they are defined in, avoiding any remapping conflicts. Read more about remappings in the Using Solidity remappings guide.

The @nomicfoundation/hardhat-foundry plugin

Some Foundry projects don’t use remappings.txt files, but instead rely on forge to autogenerate them. If this is the case for your project, or any of your dependencies, you should install the @nomicfoundation/hardhat-foundry plugin.

To install it, run:

npm

npm add --save-dev @nomicfoundation/hardhat-foundry

pnpm

pnpm add --save-dev @nomicfoundation/hardhat-foundry

Yarn

yarn add --dev @nomicfoundation/hardhat-foundry

Then, add it to your Hardhat config:

hardhat.config.ts

import { HardhatUserConfig } from "hardhat/config";
// ...
import hardhatFoundry from "@nomicfoundation/hardhat-foundry";

const config: HardhatUserConfig = {
  // ... rest of the config
  plugins: [..., hardhatFoundry],
};

Solidity tests compatibility

Hardhat 3 can run Solidity tests by default, including those previously built for Foundry. Learn more about writing and running Solidity tests in Hardhat 3 by reading the Writing Solidity tests guide, and the Cheatcodes reference documentation.

To learn how to configure the Solidity tests runner, read the Configuration reference documentation.

Separate build process and test artifacts

Hardhat 3 builds smart contracts and tests as separate build processes. On top of that, it doesn’t expose the build artifacts of tests to users, and considers them internal and part of the cache/ directory.