PaulRBerg/hardhat-template for Solidity development

What the template provides for Solidity teams

PaulRBerg/hardhat-template addresses the initial setup work required by a new Solidity project. It is aimed at developers who want Hardhat as the local development environment and TypeScript as the language for configuration, tests, deployment scripts, and generated contract bindings. The repository description calls it a Hardhat-based template for developing Solidity smart contracts, and the package metadata places the project in the blockchain, Ethereum, Solidity, Hardhat, and TypeScript ecosystem.

The template combines several tools that would otherwise need to be selected and configured separately. The README identifies Hardhat for compiling, running, and testing contracts; TypeChain for generating TypeScript bindings; Ethers for Ethereum library and wallet functionality; Solhint for Solidity linting; Solcover through `solidity-coverage` for coverage; and Prettier Plugin Solidity for formatting. The repository also contains `.eslintrc.yml`, `.prettierrc.yml`, `.solhint.json`, `.solcover.js`, `.editorconfig`, and ignore files. These defaults make the starting point more opinionated than a bare contract repository.

This is a template, not a contract library. The README does not claim that it provides reusable contracts, an upgrade framework, a production deployment system, or a security review process. Its value is the assembled development structure and its ready-made commands.

The TypeScript and Hardhat development flow

The visible architecture follows Hardhat's normal contract-development path. Solidity files live under `contracts/`, while repository entries such as `test/`, `deploy/`, and `tasks/` provide separate areas for tests, deployment work, and custom Hardhat tasks. `hardhat.config.ts` is the central TypeScript configuration file. The package metadata also includes TypeScript, `ts-node`, Hardhat plugins, Ethers, TypeChain, and test-related packages.

Compilation produces Hardhat artifacts. The documented `bun run typechain` command compiles contracts and generates TypeChain bindings, allowing TypeScript code to interact with contract interfaces through generated bindings rather than relying only on manually maintained ABI representations. The Ethers dependency and `@typechain/ethers-v6` package connect those bindings to Ethers v6. This is a development-time convenience, but the README does not document how generated files are committed or regenerated in a continuous deployment process.

Hardhat Network is used for local execution. The deployment command targets Hardhat Network, while the README separately documents Ganache for a deterministic local development blockchain. Tests are run through Hardhat and can include gas reporting. The repository therefore supports a local loop from source code to compiled artifacts, generated TypeScript bindings, tests, and deployment tasks. The README does not describe a production RPC provider beyond the configurable Hardhat variables.

Installation, configuration, and a first local deployment

The documented first step is to create a repository from the template with the `Use this template` button. The README then uses Bun for dependency installation and scripts. Install the project dependencies with:

bun install

After installation, Hardhat configuration variables must be set. The README points to Hardhat's configuration-variable documentation and provides a setup command. Run the interactive setup helper with:

bunx hardhat vars setup

For a specific value, such as `MNEMONIC`, use:

bunx hardhat vars set MNEMONIC

The command prompts for the value. The README also mentions `INFURA_API_KEY` as a value used by the default GitHub Actions workflow. It does not document a required local value for that variable beyond the configuration-variable reference.

Compile the contracts with:

bun run compile

Run the test suite with:

bun run test

A first deployment to the local Hardhat Network is performed with:

bun run deploy:contracts

For a custom Lock deployment task, the README gives this invocation:

bun run task:deployLock --unlock 100 --value 0.1

The task example passes `--unlock` and `--value`. The README does not specify the network on which this task runs beyond the surrounding Hardhat configuration and deployment commands.

Testing, linting, coverage, and gas reporting

The template includes separate quality checks for Solidity and TypeScript. Solidity linting is exposed through `bun run lint:sol`, while TypeScript linting uses `bun run lint:ts`. Formatting is supported by Prettier Plugin Solidity and the repository's `.prettierrc.yml`. Solhint rules are defined in `.solhint.json`.

Coverage uses Solcover through `solidity-coverage`. The documented command is:

bun run coverage

The README says that Gitpod can display the generated coverage report through `Go Live`. It does not specify an output directory or an exact browser URL, so those details should come from the generated report and local environment.

Gas reporting is optional and is controlled with the `REPORT_GAS` environment variable:

REPORT_GAS=true bun run test

According to the README, this reports gas usage per unit test and average gas per method call. That is a measurement aid, not a performance guarantee. The repository does not provide a benchmark suite or claim a target gas budget. The distinction matters because gas results can depend on the contract, compiler configuration, test setup, and network state.

GitHub Actions is preconfigured in `.github/workflows/ci.yml`. The README states that contracts are linted and tested on every push and pull request targeting `main`. Its default workflow uses test values for `MNEMONIC` and `INFURA_API_KEY`; repository owners can replace them with GitHub secrets.

Local Ganache workflow and its boundary

The README provides an alternative local blockchain path using Ganache. It first gives the installation command:

npm i -g ganache

It then starts a deterministic development blockchain with:

ganache -s test

The README explains that `-s test` passes a seed to the local chain, making it deterministic. For this workflow, the `MNEMONIC` configured for the project should match the mnemonic used by the Ganache instance. The setup command is:

bunx hardhat vars set MNEMONIC

This is useful when a developer wants a separate local chain rather than relying only on Hardhat Network. It also introduces an alignment requirement between the project's configured mnemonic and the Ganache process. If those values differ, account addresses and deployment targets may not correspond to the intended accounts. The README does not document a cleanup command for Ganache state, a port setting, or a production deployment path from this local setup.

The main limitation is scope. Ganache is presented as a local development blockchain, not as a production network. The repository's examples therefore establish a repeatable development loop, but they do not establish an operational process for managed RPC endpoints, key custody, contract verification, or deployment recovery.

Maintenance, licensing, and upgrade considerations

The repository is not archived, and the recorded last push was on 2026-10-09. That indicates recent repository activity, but the project has no GitHub releases, so there is no release history to use as an upgrade path. The package metadata lists dependencies with caret ranges, including Hardhat `^2.19.2`, TypeScript `^5.3.3`, Ethers `^6.9.0`, TypeChain `^8.3.2`, and Solhint `^4.0.0`. A generated project may therefore need dependency updates after creation, and the repository does not state a compatibility policy for future Hardhat or TypeChain releases.

The repository is licensed under MIT. The README and repository metadata identify that license, and the LICENSE.md file is present. MIT licensing does not remove the need to review dependency licenses or the obligations in the license text. This article does not interpret the license or provide legal advice.

Upgrade cost is concentrated in configuration and generated bindings. Hardhat configuration changes can affect compilation and tests, TypeChain changes can alter generated TypeScript interfaces, and Ethers v6 integration can require different code patterns from older Ethers examples. The README does not document migration notes, rollback procedures, or release-specific upgrade instructions. Those are concrete items to inspect before reusing the template for an established contract system.

When to choose a different Solidity setup

This template is a reasonable fit when the project starts with Hardhat and Bun, uses TypeScript for contract-related tooling, and wants linting, coverage, gas reporting, TypeChain bindings, deployment scripts, custom tasks, and CI included from the beginning. The documented commands also make the intended workflow visible, which is useful when a team wants a baseline rather than an empty repository.

A different approach may be better when a project does not use Hardhat, does not want Bun, or requires a deployment, testing, or verification workflow that the template does not document. The README does not compare this template with Foundry, so the relevant distinction is only that this repository is built around Hardhat's TypeScript workflow. It is not a neutral Solidity setup, and its included scripts assume that toolchain.

The template is also not a substitute for contract architecture. It does not state anything about proxy patterns, access-control review, formal verification, upgradeability, or production incident handling. Those concerns belong outside the starter configuration and must be established by the adopting team.

Editorial conclusion

Adopt PaulRBerg/hardhat-template when a new Solidity project wants a TypeScript Hardhat setup with generated bindings, Ethers integration, linting, coverage, deployment tasks, and CI already represented in the repository. Do not adopt it without reviewing the included configuration and dependency versions if you need a different toolchain or package manager. Before starting contract work, verify `hardhat.config.ts`, the environment variables, the test network, and the deployment task because the README documents defaults but does not describe rollback, production deployment procedures, or contract upgrade policy. The repository is not archived, and its last push was on 2026-10-09, while its MIT license permits reuse subject to the license terms.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. PaulRBerg/hardhat-template on GitHub
4. README