0
# Hardhat Toolbox Viem
1

2
The Hardhat Toolbox Viem provides a comprehensive set of plugins to build Hardhat projects with [viem](https://viem.sh/) as the connection library and the [Node.js test runner](https://nodejs.org/api/test.html) for TypeScript tests. It's the recommended toolbox for new Hardhat projects that prioritize type safety and modern blockchain development.
3

4
## Package Information
5

6
- **Package Name**: @nomicfoundation/hardhat-toolbox-viem
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install --save-dev @nomicfoundation/hardhat-toolbox-viem`
10

11
## Core Imports
12

13
```typescript
14
import hardhatToolboxViem from "@nomicfoundation/hardhat-toolbox-viem";
15
```
16

17
For CommonJS (though not recommended with this package):
18

19
```javascript
20
const hardhatToolboxViem = require("@nomicfoundation/hardhat-toolbox-viem").default;
21
```
22

23
## Basic Usage
24

25
Add the toolbox to your Hardhat configuration file:
26

27
```typescript
28
import type { HardhatUserConfig } from "hardhat/types/config";
29
import hardhatToolboxViem from "@nomicfoundation/hardhat-toolbox-viem";
30

31
const config: HardhatUserConfig = {
32
  plugins: [hardhatToolboxViem],
33
  solidity: "0.8.19",
34
  // Your other configuration...
35
};
36

37
export default config;
38
```
39

40
Once configured, you can use all the bundled plugins in your scripts and tests:
41

42
```typescript
43
import hre from "hardhat";
44

45
// Use network helpers
46
await hre.network.provider.send("hardhat_mine", ["0x1"]);
47

48
// Use viem for type-safe contract interactions  
49
const publicClient = await hre.viem.getPublicClient();
50
const walletClients = await hre.viem.getWalletClients();
51
```
52

53
## Architecture
54

55
The Hardhat Toolbox Viem is a plugin bundler that automatically loads and configures essential Hardhat plugins for viem-based development:
56

57
- **Plugin Bundle**: Automatically loads 7 core plugins as dependencies
58
- **Type Extensions**: Re-exports TypeScript types from all bundled plugins
59
- **Peer Dependencies**: Manages plugin versions through peer dependency system
60
- **ESM Module**: Built as an ES module for modern JavaScript compatibility
61

62
## Capabilities
63

64
### Default Export
65

66
The package exports a single default plugin object that can be imported and used in Hardhat configurations.
67

68
```typescript { .api }
69
/**
70
 * Default export of the hardhat-toolbox-viem plugin
71
 */
72
export default hardhatToolboxViemPlugin: HardhatPlugin;
73
```
74

75
### Plugin Definition
76

77
The main export that defines the Hardhat plugin and its dependencies.
78

79
```typescript { .api }
80
/**
81
 * Main plugin object that defines the toolbox and its bundled dependencies
82
 */
83
declare const hardhatToolboxViemPlugin: HardhatPlugin;
84

85
interface HardhatPlugin {
86
  /** Unique identifier for the plugin */
87
  readonly id: string;
88
  /** Function returning array of import promises for plugin dependencies */
89
  readonly dependencies: () => Promise<any>[];
90
  /** NPM package name */
91
  readonly npmPackage: string;
92
}
93
```
94

95
**Plugin Properties:**
96

97
```typescript { .api }
98
/** Plugin identifier */
99
id: "hardhat-toolbox-viem";
100

101
/** NPM package name */
102
npmPackage: "@nomicfoundation/hardhat-toolbox-viem";
103

104
/** Bundled plugin dependencies loaded dynamically */
105
dependencies: () => [
106
  import("@nomicfoundation/hardhat-ignition-viem"),
107
  import("@nomicfoundation/hardhat-keystore"),
108
  import("@nomicfoundation/hardhat-network-helpers"),
109
  import("@nomicfoundation/hardhat-node-test-runner"),
110
  import("@nomicfoundation/hardhat-viem"),
111
  import("@nomicfoundation/hardhat-viem-assertions"),
112
  import("@nomicfoundation/hardhat-verify")
113
];
114
```
115

116
### Type Extensions
117

118
Re-exported TypeScript types from all bundled plugins for enhanced development experience.
119

120
```typescript { .api }
121
/** All types from hardhat-ignition-viem plugin */
122
export type * from "@nomicfoundation/hardhat-ignition-viem";
123

124
/** All types from hardhat-keystore plugin */
125
export type * from "@nomicfoundation/hardhat-keystore";
126

127
/** All types from hardhat-network-helpers plugin */
128
export type * from "@nomicfoundation/hardhat-network-helpers";
129

130
/** All types from hardhat-node-test-runner plugin */
131
export type * from "@nomicfoundation/hardhat-node-test-runner";
132

133
/** All types from hardhat-viem plugin */
134
export type * from "@nomicfoundation/hardhat-viem";
135

136
/** All types from hardhat-viem-assertions plugin */
137
export type * from "@nomicfoundation/hardhat-viem-assertions";
138

139
/** All types from hardhat-verify plugin */
140
export type * from "@nomicfoundation/hardhat-verify";
141
```
142

143
## Bundled Plugins
144

145
When you install the toolbox, these plugins are automatically available:
146

147
- **hardhat-ignition-viem**: Contract deployment using Hardhat Ignition with viem
148
- **hardhat-keystore**: Encrypted keystore management for private keys
149
- **hardhat-network-helpers**: Testing utilities for network manipulation (mining, time travel, etc.)
150
- **hardhat-node-test-runner**: TypeScript test runner integration
151
- **hardhat-viem**: Core viem integration for Hardhat
152
- **hardhat-viem-assertions**: Testing assertions specifically designed for viem
153
- **hardhat-verify**: Contract verification on block explorers
154

155
## Manual Plugin Installation
156

157
In some cases, you may need to explicitly install one of the bundled plugins:
158

159
```bash
160
npm install --save-dev @nomicfoundation/hardhat-viem-assertions
161
```
162

163
This allows you to import specific utilities:
164

165
```typescript
166
import { anyValue } from "@nomicfoundation/hardhat-viem-assertions/predicates";
167

168
// Use in tests
169
expect(contract).to.emit.withArgs(anyValue, "expected value");
170
```
171

172
## Integration with Hardhat
173

174
The toolbox integrates seamlessly with Hardhat's task system. After installation, you'll have access to:
175

176
- `hardhat test` with Node.js test runner support
177
- `hardhat ignition` for contract deployment
178
- `hardhat verify` for contract verification
179
- `hardhat keystore` for key management
180
- Enhanced `hardhat run` with viem and network helpers
181

182
## Types
183

184
```typescript { .api }
185
/** Main plugin definition interface from Hardhat core */
186
interface HardhatPlugin {
187
  /** Unique plugin identifier */
188
  readonly id: string;
189
  /** Function returning array of import promises for plugin dependencies */
190
  readonly dependencies: () => Promise<any>[];
191
  /** NPM package name for the plugin */
192
  readonly npmPackage: string;
193
}
194
```
195

196