Install hardhat-kms

This page installs hardhat-kms and the provider package for your cloud with npm, pnpm or Yarn, registers the plugin in hardhat.config.ts and checks that Hardhat lists its tasks.

hardhat-kms is two packages: the core, hardhat-kms, and the provider package for the cloud that holds your key. Install both at the same version:

Cloud	Provider package	Plugin export
AWS KMS	@hardhat-kms/aws	hardhatKmsAws
Google Cloud KMS	@hardhat-kms/gcp	hardhatKmsGcp
Azure Key Vault or Managed HSM	@hardhat-kms/azure	hardhatKmsAzure

The packages need Hardhat ^3.18.0 and one of the supported Node.js versions. Run the steps in a Hardhat 3 project. If you have none yet, npx hardhat --init (pnpm dlx hardhat --init, yarn dlx hardhat --init) creates one in a new directory.

To start from an empty directory instead, create a package.json with "type": "module" first. Hardhat 3 runs only in ES module projects: without that field, step 3 stops with "Hardhat only supports ESM projects".

npm

npm init -y
npm pkg set type=module

pnpm

pnpm init
pnpm pkg set type=module

Yarn

yarn init -2
npm pkg set type=module

yarn init -2 sets the directory up for Yarn 4; with Yarn 1, run yarn init -y instead.

NOTE

Audience: people adding hardhat-kms to a Hardhat 3 project.

1. Install the packages

The commands below install the AWS provider. For another cloud, replace @hardhat-kms/aws with the package from the table.

npm

npm install --save-dev "hardhat@^3.18.0" hardhat-kms @hardhat-kms/aws

pnpm

pnpm add --save-dev "hardhat@^3.18.0" hardhat-kms @hardhat-kms/aws

Yarn

yarn add --dev "hardhat@^3.18.0" hardhat-kms @hardhat-kms/aws

The command names hardhat because the plugin packages list it as a peer dependency, and Yarn does not install peers. It also raises an older Hardhat 3 to 3.18. connection.kms.getAccount needs viem ^2.55.13 as well; ethers and Ignition projects can skip it (Library accounts).

If the install stops

Find the message in the table, then follow the section for your package manager. A release-age gate can also select an older version without failing:

Package manager	What you see	Fix
npm 11 and 12	A warning, or blocked install scripts, for esbuild and others	None: the plugin needs none of these scripts (npm).
pnpm 11 and later	ERR_PNPM_IGNORED_BUILDS	List the packages it names under allowBuilds in pnpm-workspace.yaml with the value false, then run pnpm install (pnpm).
Yarn 4	HHE22 from yarn hardhat	Set nodeLinker: node-modules in .yarnrc.yml, then run yarn install again (Yarn).
pnpm 11 and later	An older version during the release-age window	Check the installed versions. To select a newer release now, use a package-scoped minimumReleaseAgeExclude (pnpm).
Yarn 4.15 and later	An older version, or YN0016, during the release-age window	Check the installed versions. To select a newer release now, use npmPreapprovedPackages (Yarn).
Yarn 4.14 and later	YN0004 for esbuild and protobufjs	None: the plugin needs neither script (Yarn).

npm

npm needs no settings. npm 11 warns that esbuild, and protobufjs with Google Cloud, have install scripts "not yet covered by allowScripts". npm 12 blocks those scripts and lists the packages: esbuild, protobufjs with Google Cloud, and fsevents on macOS. The plugin needs none of them, so leave them blocked.

pnpm

pnpm 11 and later stop with ERR_PNPM_IGNORED_BUILDS because two dependencies have install scripts: esbuild, which Hardhat depends on, and protobufjs, which the Google Cloud SDK depends on. The packages are installed, but the command exits with an error. Neither script is needed: esbuild's script checks its platform binary, and protobufjs's script prints a warning. Add this to pnpm-workspace.yaml, next to package.json, then run pnpm install:

allowBuilds:
  esbuild: false
  protobufjs: false # Google Cloud only

If pnpm names other packages, add each one under allowBuilds with the value false too; the plugin needs none of their install scripts.

pnpm 10 prints the same list as a warning and installs; it needs no change.

pnpm 11 and later have a one-day release-age gate by default. If an older version satisfies the dependency range, pnpm can install it while the newer version is too young. Check with pnpm list hardhat-kms @hardhat-kms/aws; use your provider's package name for another cloud.

To select a newly published release now, add these package-scoped exceptions to pnpm-workspace.yaml, then run pnpm add again. Other dependencies keep their release-age gate. Remove the exceptions after the intended release is old enough for your configured gate:

minimumReleaseAgeExclude:
  - hardhat-kms
  - "@hardhat-kms/*"

For an acceptance test or another exact-version install, name the version in both package specs, such as hardhat-kms@0.10.1 @hardhat-kms/aws@0.10.1. The pnpm settings also allow version-specific exceptions.

Yarn

Yarn 1 needs no settings.

Yarn 4 needs nodeLinker: node-modules in .yarnrc.yml, next to package.json, before the install. Hardhat does not run under Plug'n'Play, Yarn 4's default linker: under it, yarn hardhat stops with HHE22 ("Trying to use a non-local installation of Hardhat").

nodeLinker: node-modules

From Yarn 4.15, Yarn skips versions younger than its npmMinimalAgeGate (1440 minutes by default). It can select an older version or fail with YN0016 when no eligible version satisfies the request. Check with yarn why hardhat-kms and yarn why @hardhat-kms/aws; use your provider's package name for another cloud.

To select a newly published release now, add this line to .yarnrc.yml and run yarn add again. Other packages keep their gates. Remove the line after the intended release is old enough for your configured gate. Yarn 4.10 to 4.14 accept it but do not need it; Yarn 4.9 and earlier refuse it as an unknown setting:

npmPreapprovedPackages: ["hardhat-kms", "@hardhat-kms/*"]

For an exact-version install, name the same version in both package specs, such as hardhat-kms@0.10.1 @hardhat-kms/aws@0.10.1. Yarn's settings describe the package gates and exceptions.

Yarn 4.14 and later run no install scripts by default and print YN0004 for esbuild and protobufjs; the plugin needs neither.

@hardhat-kms/gcp: Yarn 1 and pnpm 10 can install the deprecated google-gax 6.11.0; Keep google-gax off 6.11.0 says how to check and how to override it.

2. Register the plugin

Add the provider package to plugins in hardhat.config.ts. It loads hardhat-kms itself:

AWS KMS

import hardhatKmsAws from "@hardhat-kms/aws";
import { defineConfig } from "hardhat/config";

export default defineConfig({
  plugins: [hardhatKmsAws],
});

Google Cloud KMS

import hardhatKmsGcp from "@hardhat-kms/gcp";
import { defineConfig } from "hardhat/config";

export default defineConfig({
  plugins: [hardhatKmsGcp],
});

Azure Key Vault

import hardhatKmsAzure from "@hardhat-kms/azure";
import { defineConfig } from "hardhat/config";

export default defineConfig({
  plugins: [hardhatKmsAzure],
});

In a project from npx hardhat --init, add the import and append the plugin to the existing plugins list. In an empty directory, save the block as hardhat.config.ts.

3. Check the install

npm

npx hardhat kms --help

pnpm

pnpm hardhat kms --help

Yarn

yarn hardhat kms --help

Hardhat lists the plugin's tasks: kms accounts, kms address, kms history, kms public-key, kms sign, kms sign-auth, kms sign-tx and kms verify. If it answers Error HHE404: Task "kms" not found, the packages are installed but the plugin is not in plugins: go back to step 2.

Next, create a key and add it to the config: Set up an AWS KMS key, Set up a Google Cloud KMS key or Set up an Azure Key Vault key. The Configuration reference lists every option.

Install a build from the repository

To try a commit that is not on npm, such as a fix on main, build the packages from a clone, pack them and install the packed files. For anything else, install from npm.

Building needs:

• Git, to clone the repository.
• Node.js 22.18 or later. The repository's scripts are TypeScript files that run with plain node.
• pnpm 12, which the repository pins in packageManager. Run corepack enable, or npm install -g pnpm@12.8.1.

Your Hardhat project needs none of them: it uses the packed files with npm, pnpm or Yarn on the supported Node.js versions.

git clone https://github.com/aelmanaa/hardhat-kms.git
cd hardhat-kms
pnpm install
pnpm build
(cd packages/hardhat-kms && pnpm pack)
(cd packages/hardhat-kms-aws && pnpm pack)

For another cloud, pack packages/hardhat-kms-gcp or packages/hardhat-kms-azure instead of packages/hardhat-kms-aws. Each pnpm pack writes a .tgz file into its package directory, named after the package and the version in its package.json: hardhat-kms-<version>.tgz and hardhat-kms-aws-<version>.tgz. The provider's file name has no @ or /.

Copy the two files into your Hardhat project and install them by path. <clone> is the path to your clone, and <version> the version in the file names. The install records the path in package.json, so a copy inside the project keeps working after the clone moves:

npm

mkdir -p vendor
cp <clone>/packages/hardhat-kms/hardhat-kms-<version>.tgz <clone>/packages/hardhat-kms-aws/hardhat-kms-aws-<version>.tgz vendor/
npm install --save-dev ./vendor/hardhat-kms-<version>.tgz ./vendor/hardhat-kms-aws-<version>.tgz

pnpm

mkdir -p vendor
cp <clone>/packages/hardhat-kms/hardhat-kms-<version>.tgz <clone>/packages/hardhat-kms-aws/hardhat-kms-aws-<version>.tgz vendor/
pnpm add --save-dev ./vendor/hardhat-kms-<version>.tgz ./vendor/hardhat-kms-aws-<version>.tgz

Yarn

mkdir -p vendor
cp <clone>/packages/hardhat-kms/hardhat-kms-<version>.tgz <clone>/packages/hardhat-kms-aws/hardhat-kms-aws-<version>.tgz vendor/
yarn add --dev ./vendor/hardhat-kms-<version>.tgz ./vendor/hardhat-kms-aws-<version>.tgz

The pnpm and Yarn notes above apply here too. Then continue at step 2.