or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-nomicfoundation--hardhat-toolbox-viem

Nomic Foundation's recommended bundle of Hardhat plugins for viem-based blockchain development

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@nomicfoundation/hardhat-toolbox-viem@5.0.x

To install, run

npx @tessl/cli install tessl/npm-nomicfoundation--hardhat-toolbox-viem@5.0.0

index.mddocs/

Hardhat Toolbox Viem

The Hardhat Toolbox Viem provides a comprehensive set of plugins to build Hardhat projects with viem as the connection library and the Node.js test runner for TypeScript tests. It's the recommended toolbox for new Hardhat projects that prioritize type safety and modern blockchain development.

Package Information

  • Package Name: @nomicfoundation/hardhat-toolbox-viem
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install --save-dev @nomicfoundation/hardhat-toolbox-viem

Core Imports

import hardhatToolboxViem from "@nomicfoundation/hardhat-toolbox-viem";

For CommonJS (though not recommended with this package):

const hardhatToolboxViem = require("@nomicfoundation/hardhat-toolbox-viem").default;

Basic Usage

Add the toolbox to your Hardhat configuration file:

import type { HardhatUserConfig } from "hardhat/types/config";
import hardhatToolboxViem from "@nomicfoundation/hardhat-toolbox-viem";

const config: HardhatUserConfig = {
  plugins: [hardhatToolboxViem],
  solidity: "0.8.19",
  // Your other configuration...
};

export default config;

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

import hre from "hardhat";

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

// Use viem for type-safe contract interactions  
const publicClient = await hre.viem.getPublicClient();
const walletClients = await hre.viem.getWalletClients();

Architecture

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

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

Capabilities

Default Export

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

/**
 * Default export of the hardhat-toolbox-viem plugin
 */
export default hardhatToolboxViemPlugin: HardhatPlugin;

Plugin Definition

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

/**
 * Main plugin object that defines the toolbox and its bundled dependencies
 */
declare const hardhatToolboxViemPlugin: HardhatPlugin;

interface HardhatPlugin {
  /** Unique identifier for the plugin */
  readonly id: string;
  /** Function returning array of import promises for plugin dependencies */
  readonly dependencies: () => Promise<any>[];
  /** NPM package name */
  readonly npmPackage: string;
}

Plugin Properties:

/** Plugin identifier */
id: "hardhat-toolbox-viem";

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

/** Bundled plugin dependencies loaded dynamically */
dependencies: () => [
  import("@nomicfoundation/hardhat-ignition-viem"),
  import("@nomicfoundation/hardhat-keystore"),
  import("@nomicfoundation/hardhat-network-helpers"),
  import("@nomicfoundation/hardhat-node-test-runner"),
  import("@nomicfoundation/hardhat-viem"),
  import("@nomicfoundation/hardhat-viem-assertions"),
  import("@nomicfoundation/hardhat-verify")
];

Type Extensions

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

/** All types from hardhat-ignition-viem plugin */
export type * from "@nomicfoundation/hardhat-ignition-viem";

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

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

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

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

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

/** All types from hardhat-verify plugin */
export type * from "@nomicfoundation/hardhat-verify";

Bundled Plugins

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

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

Manual Plugin Installation

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

npm install --save-dev @nomicfoundation/hardhat-viem-assertions

This allows you to import specific utilities:

import { anyValue } from "@nomicfoundation/hardhat-viem-assertions/predicates";

// Use in tests
expect(contract).to.emit.withArgs(anyValue, "expected value");

Integration with Hardhat

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

  • hardhat test with Node.js test runner support
  • hardhat ignition for contract deployment
  • hardhat verify for contract verification
  • hardhat keystore for key management
  • Enhanced hardhat run with viem and network helpers

Types

/** Main plugin definition interface from Hardhat core */
interface HardhatPlugin {
  /** Unique plugin identifier */
  readonly id: string;
  /** Function returning array of import promises for plugin dependencies */
  readonly dependencies: () => Promise<any>[];
  /** NPM package name for the plugin */
  readonly npmPackage: string;
}