hardhat-deploy

A Hardhat Plugin For Replicable Deployments And Easy Testing

Note: This is the documentation for hardhat-deploy v2 that works with hardhat v3

Documentation for hardhat-deploy v1 can be found on the v1 branch

Overview

hardhat-deploy makes it easy for you to deploy your EVM smart contracts across many chains while keeping track of them and replicating the same environment for testing.

It adds a mechanism to associate names to addresses, so test and deployment scripts can be reconfigured by simply changing the address a name points to. This results in much clearer tests and deployment scripts — no more accounts[0] in your code.

Why hardhat-deploy + rocketh?

While Hardhat's official Ignition plugin offers a robust deployment system, it comes with a rigid DSL that limits flexibility. hardhat-deploy + rocketh provides:

• Intuitive Deployment Scripts: Write deployment logic in plain TypeScript without learning a new DSL.
• Browser-Compatible Deployments: Thanks to rocketh's framework-agnostic design, your deployment scripts can be executed directly in the browser — enabling in-app deployments, testing in web environments, and seamless integration with web frontends.
• Hot Contract Replacement (HCR): The equivalent of HMR (Hot Module Replacement) for smart contracts. Edit your contracts and see changes live while developing your app or game using proxy patterns with conventions that make it work seamlessly.
• Flexible Proxy Patterns: Declarative proxy deployment with deployViaProxy for upgradeable contracts, including support for OpenZeppelin transparent proxies.
• Diamond Support: Deploy EIP-2535 Diamonds declaratively — specify the new state and let hardhat-deploy generate the diamondCut for you.
• Full Control: Access to all deployment parameters and lifecycle hooks.

Architecture

Version 2 is a full rewrite that has been used in production for several years. It is fully modular, making it much easier to contribute new deployment mechanisms.

Under the hood, hardhat-deploy uses rocketh, a framework-agnostic system that provides a minimal API to save and load deployments. Everything else is handled by external modules:

Module	Description
@rocketh/deploy	Provides a deploy() function to deploy contracts
@rocketh/proxy	deployViaProxy() for upgradeable contracts
@rocketh/diamond	diamond() for EIP-2535 Diamond deployments
@rocketh/read-execute	read(), execute(), readByName(), executeByName(), tx()
@rocketh/viem	Viem client integration with getContract(), getWritableContract()
@rocketh/export	Export deployments to JS/TS/JSON formats
@rocketh/verifier	Verify contracts on Etherscan, Sourcify, or Blockscout

You can also provide your own modules for advanced use cases.

Getting Started

To get started with hardhat-deploy, see the Installation Guide, or jump straight into learning How to Deploy Contracts.

For a production-ready setup, check out the template-ethereum-contracts template.