Hardhat Boilerplate with Local Solidity Compiler

This boilerplate solves the HH502 error (unable to download compiler from the internet) by using a local Solidity compiler from node_modules.

🚀 Features

• ✅ Works offline - uses local solc from node_modules
• ✅ Solves HH502 error - no need to download compiler from the network
• ✅ Hardhat 2.x configured - latest version with TypeScript support

📋 Requirements

• Node.js 18.x or 20.x (LTS versions)
• npm or yarn

⚠️ Important: Hardhat does not support Node.js versions above 20. If you have Node.js 23+, use nvm to switch:

nvm install 20
nvm use 20

🛠️ Installation

# Clone the repository
git clone <your-repo-url>
cd hello-hardhat

# Install dependencies
npm install

🔧 How It Works

The problem is solved by overriding the TASK_COMPILE_SOLIDITY_GET_SOLC_BUILD task in hardhat.config.ts:

subtask(
  TASK_COMPILE_SOLIDITY_GET_SOLC_BUILD,
  async (args: { solcVersion: string }, hre, runSuper) => {
    if (args.solcVersion === "0.8.28") {
      const compilerPath = path.join(
        __dirname,
        "node_modules/solc/soljson.js"
      );

      return {
        compilerPath,
        isSolcJs: true,
        version: args.solcVersion,
        longVersion: "0.8.28+commit.xxx",
      };
    }

    return runSuper();
  }
);

This forces Hardhat to use the local soljson.js instead of trying to download it from the internet.

📝 Usage

Compile contracts

npm run compile
# or
npx hardhat compile

Run tests

npm run test
# or
npx hardhat test

Start local node

npm run node
# or
npx hardhat node

Deploy contract

npx hardhat ignition deploy ./ignition/modules/Lock.ts

🔄 Using in Other Projects

1. Copy hardhat.config.ts to your project
2. Make sure solc is installed: npm install --save-dev solc@0.8.28
3. Update the Solidity version in the configuration if you're using a different version
4. For other Solidity versions, add additional conditions in the subtask

Example for multiple versions:

subtask(
  TASK_COMPILE_SOLIDITY_GET_SOLC_BUILD,
  async (args: { solcVersion: string }, hre, runSuper) => {
    const version = args.solcVersion;
    
    if (version === "0.8.28" || version === "0.8.27") {
      const compilerPath = path.join(
        __dirname,
        `node_modules/solc-${version}/soljson.js`
      );

      return {
        compilerPath,
        isSolcJs: true,
        version: version,
        longVersion: `${version}+commit.xxx`,
      };
    }

    return runSuper();
  }
);

🐛 Troubleshooting

HH502 Error: Couldn't download compiler version list

✅ Solved in this boilerplate - uses local compiler

Node.js version warning

If you see a warning about unsupported Node.js version:

• Use Node.js 18.x or 20.x (LTS)
• Install via nvm: nvm install 20 && nvm use 20

Compiler not found

Make sure solc is installed:

npm install --save-dev solc@0.8.28

📚 Useful Links

• Hardhat Documentation
• Solidity Documentation
• Hardhat GitHub

📄 License

ISC