Skip to content
Hardhat 3

Isolated Builds

Isolated Builds mode makes it easier to reproduce builds and verify your contracts on block explorers.

Understanding Hardhat compilation jobs

Section titled “Understanding Hardhat compilation jobs”

When you run

Terminal window
npx undefined

Hardhat will compile your contracts and your tests as two separate processes.

When compiling your contracts, it will select every .sol file (not .t.sol) in contracts/ and create a compilation job based on the highest version of Solidity from your config that it can use. To learn more about this, read the Using multiple versions of Solidity in a single project guide.

The same process is done for your Solidity tests, compiling every .sol file in test/ and every .t.sol file in contracts/.

By default, Hardhat may decide to merge some compilation jobs if they use the same Solidity version and settings. This can lead to faster compilation times and smaller artifacts.

For example, in this project:

  • Directorymy-project/
    • package.json
    • hardhat.config.ts
    • Directorycontracts/
      • MyContract.sol
      • AnotherContract.sol

The files contracts/MyContract.sol and contracts/AnotherContract.sol might be built in the same compilation job, depending on your existing compilation cache and settings.

Drawbacks of merging compilation jobs

Section titled “Drawbacks of merging compilation jobs”

Merging compilation jobs isn’t ideal when building contracts with the intention of deploying them:

  • The dependence on the compilation cache can make reproducing builds complex
  • You may need to submit unrelated files during verification. For example, when verifying contracts/MyContract.sol, you might also need to submit contracts/AnotherContract.sol.

Isolated Builds

Section titled “Isolated Builds”

To avoid the drawbacks explained above, Hardhat 3 introduced the concept of Isolated Builds.

When Isolated Builds are used, each of the files in contracts/ is built independently, only including its dependencies.

To enable this mode, modify your solidity config like this:

hardhat.config.ts
import { defineConfig } from "hardhat/config";


export default defineConfig({
  //...
  solidity: {
    version: "0.8.29",
    isolated: true,
  },
});

The isolated flag is also available when using multiple versions of Solidity and Build Profiles.