Replace `debug` package with in-tree `createDebug` helper by schaable · Pull Request #8192 · NomicFoundation/hardhat

schaable · 2026-04-25T18:25:48Z

Overview

Replaces the debug npm dependency across the monorepo with createDebug, a small zero-dependency logger factory that lives in @nomicfoundation/hardhat-utils.

It keeps the same call-site shape (const log = createDebug("namespace")) and the same DEBUG filter syntax, while adding a faster disabled-emit path (NOOP short-circuit) and a richer 49-color palette that makes namespaces easier to distinguish.

Review notes:

While large, this PR is split into commits that can be reviewed individually. The largest one is mechanical and replaces debug with createDebug across the monorepo.

The withDebugLogs decorator is removed in this PR. It had no call sites in the monorepo and its own JSDoc said it was meant for ad-hoc local debugging and shouldn't be committed in runtime code.

Closes #8161.

Differences against `debug`

Only DEBUG and DEBUG_COLORS env vars are honoured; others (e.g. DEBUG_DEPTH, DEBUG_HIDE_DATE) are ignored.
Filters are read once when each logger is created. There is no runtime enable() / disable().
Always uses a fixed 49-color 256 palette, with red excluded. debug@4 defaults to 6 colors and only upgrades to a 76-color palette when supports-color detects a 256-color terminal. This is fine for most modern terminals, and older ones fall back to the closest supported color.
Output shape is the same with or without DEBUG_COLORS=no (only the ANSI codes change). debug switches to a different layout (with an ISO timestamp prefix) when colours are disabled.
Elapsed time is printed as +123ms, not humanized to +1s / +2m.
The returned logger only exposes .enabled; no extend, namespace, or custom formatters.

Tests

Manually compared DEBUG='hardhat:*' pnpm hardhat test output against an unmodified debug-based build on the same project. Per-line +Nms markers matched within normal run-to-run noise, from sub-ms differences to about 7 ms on individual steps. No regressions were observed that could be attributed to hardhat-utils/debug.
Smoke tests from packages/example-project:

 # Broad match — many `hardhat:*` lines on stderr
DEBUG='hardhat:*' pnpm hardhat compile

# Exact namespace — only CLI main logs appear
DEBUG='hardhat:core:cli:main' pnpm hardhat compile

# Wildcard + negation
DEBUG='hardhat:*,-hardhat:core:cli:*' pnpm hardhat compile

# DEBUG_COLORS=no — same layout, ANSI codes stripped
DEBUG='hardhat:*' DEBUG_COLORS=no pnpm hardhat compile

# Confirm output goes to stderr, not stdout
DEBUG='hardhat:*' pnpm hardhat compile > /tmp/out 2>/tmp/err
head /tmp/err

Isolated check (%O, .enabled, multi-arg, deferred logging) without the CLI:

DEBUG='demo' node --import tsx/esm -e '
import("@nomicfoundation/hardhat-utils/debug").then(({createDebug}) => {
  const log = createDebug("demo");
  console.error("enabled =", log.enabled);
  log("hello");
  log("payload %O", {a: 1});
  log("multi", 42, "/tmp/x");
  setTimeout(() => log("later"), 50);
});'

Benchmark

Compared createDebug against debug@4 on the four paths that matter inside the Hardhat monorepo.

Path	`debug@4`	`createDebug`	Δ
Cold load (mean)	5.73 ms	4.10 ms	−28%
Factory	754K ops/s	3.87M ops/s	+5.1×
Disabled emit	140M ops/s	474M ops/s	+3.4×
Enabled emit (str)	558K ops/s	1.41M ops/s	+2.5×
Enabled emit (`%O`)	266K ops/s	465K ops/s	+1.75×

The 3.4× disabled-emit speedup is the most relevant result. That’s the path hit ~150× per CLI command in production. createDebug returns a shared NOOP for disabled namespaces, while debug@4 still goes through its wrapper
and enabled check on every call.

Cold load improves by ~1.6 ms on first import, mainly from avoiding the ms dependency and keeping the implementation small.

The enabled-emit improvements come from using util.formatWithOptions (C++) instead of the JS formatter used in debug@4.

changeset-bot · 2026-04-25T18:25:53Z

🦋 Changeset detected

Latest commit: dadc2fa

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 13 packages

Name	Type
@nomicfoundation/hardhat-ethers-chai-matchers	Patch
@nomicfoundation/hardhat-network-helpers	Patch
@nomicfoundation/hardhat-typechain	Patch
@nomicfoundation/hardhat-ignition	Patch
@nomicfoundation/hardhat-keystore	Patch
@nomicfoundation/hardhat-vendored	Patch
@nomicfoundation/hardhat-ethers	Patch
@nomicfoundation/hardhat-ledger	Patch
@nomicfoundation/hardhat-verify	Patch
@nomicfoundation/hardhat-mocha	Patch
@nomicfoundation/hardhat-utils	Patch
@nomicfoundation/ignition-core	Patch
hardhat	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

github-actions · 2026-04-25T18:27:18Z

hardhat

Total size of the bundle: 246M
Total number of dependencies (including transitive): 46

List of dependencies (sorted by size)

238M	total
37M	@nomicfoundation/edr-linux-x64-musl
37M	@nomicfoundation/edr-linux-x64-gnu
34M	@nomicfoundation/edr-linux-arm64-musl
34M	@nomicfoundation/edr-linux-arm64-gnu
25M	@nomicfoundation/edr-darwin-x64
24M	@nomicfoundation/edr-win32-x64-msvc
21M	@nomicfoundation/edr-darwin-arm64
7.3M	@sentry/core
5.2M	zod
2.7M	micro-eth-signer
1.9M	@noble/curves
1.7M	undici
1.2M	@nomicfoundation/hardhat-utils
1.2M	@noble/hashes
884K	@nomicfoundation/hardhat-vendored
864K	@streamparser/json
624K	micro-packed
596K	@nomicfoundation/hardhat-errors
592K	tsx
492K	@scure/bip39
476K	@nomicfoundation/edr
408K	json-stream-stringify
368K	ethereum-cryptography
344K	fast-equals
332K	@streamparser/json-node
320K	enquirer
320K	@nomicfoundation/hardhat-zod-utils
288K	semver
200K	ws
180K	get-tsconfig
180K	chokidar
168K	esbuild
168K	@scure/base
136K	adm-zip
96K	@scure/bip32
92K	chalk
72K	@nomicfoundation/solidity-analyzer
60K	readdirp
56K	rfdc
48K	ansi-colors
44K	resolve.exports
40K	resolve-pkg-maps
36K	p-map
24K	strip-ansi
24K	env-paths
24K	ansi-regex

Copilot

Pull request overview

This PR replaces the external debug npm dependency across the monorepo with an in-tree createDebug logger factory provided by @nomicfoundation/hardhat-utils, aiming to reduce cold-load overhead and speed up the disabled logging path.

Changes:

Replaced debug imports/usages with createDebug(...) across packages (and updated a few type annotations to DebugLogger).
Removed direct debug / @types/debug dependencies from multiple package manifests and updated pnpm-lock.yaml.
Added a new @nomicfoundation/hardhat-utils debug implementation (src/debug.ts + src/internal/debug.ts) and a dedicated test suite.

Reviewed changes

Copilot reviewed 55 out of 58 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
pnpm-lock.yaml	Removes direct `debug` installs and updates snapshots/peer resolutions accordingly.
packages/ignition-core/src/internal/execution/future-processor/handlers/monitor-onchain-interaction.ts	Switches onchain interaction monitor logging to `createDebug`.
packages/ignition-core/package.json	Drops `debug` and `@types/debug` dependencies.
packages/hardhat/test/internal/builtin-plugins/console/task-action.ts	Updates tests to use `createDebug` instead of `debug`.
packages/hardhat/src/internal/config-loading.ts	Migrates config-loading logger to `createDebug`.
packages/hardhat/src/internal/cli/telemetry/telemetry-permissions.ts	Migrates telemetry permissions logger to `createDebug`.
packages/hardhat/src/internal/cli/telemetry/sentry/transport.ts	Migrates sentry transport logger to `createDebug`.
packages/hardhat/src/internal/cli/telemetry/sentry/subprocess.ts	Migrates sentry subprocess logger to `createDebug`.
packages/hardhat/src/internal/cli/telemetry/sentry/reporter.ts	Migrates sentry reporter logger to `createDebug`.
packages/hardhat/src/internal/cli/telemetry/error-reporter/global-error-handlers.ts	Migrates global error handler logger to `createDebug`.
packages/hardhat/src/internal/cli/telemetry/analytics/utils.ts	Migrates analytics utils logger to `createDebug`.
packages/hardhat/src/internal/cli/telemetry/analytics/analytics.ts	Migrates analytics logger to `createDebug`.
packages/hardhat/src/internal/cli/main.ts	Migrates CLI main logger to `createDebug` and updates logger param typing.
packages/hardhat/src/internal/cli/init/init.ts	Migrates init flow logger to `createDebug`.
packages/hardhat/src/internal/cli/banner-manager.ts	Migrates banner manager logger to `createDebug`.
packages/hardhat/src/internal/builtin-plugins/solidity/build-system/compiler/index.ts	Migrates compiler index logger to `createDebug`.
packages/hardhat/src/internal/builtin-plugins/solidity/build-system/compiler/downloader.ts	Migrates compiler downloader logger to `createDebug`.
packages/hardhat/src/internal/builtin-plugins/solidity/build-system/build-system.ts	Migrates build system logger to `createDebug`.
packages/hardhat/src/internal/builtin-plugins/node/task-action.ts	Migrates node task logger to `createDebug`.
packages/hardhat/src/internal/builtin-plugins/node/json-rpc/server.ts	Migrates JSON-RPC server logger to `createDebug`.
packages/hardhat/src/internal/builtin-plugins/node/helpers.ts	Updates logger parameter type to `DebugLogger`.
packages/hardhat/src/internal/builtin-plugins/node/artifacts/build-info-watcher.ts	Migrates build-info watcher logger to `createDebug`.
packages/hardhat/src/internal/builtin-plugins/network-manager/edr/utils/trace-output.ts	Migrates trace output logger to `createDebug`.
packages/hardhat/src/internal/builtin-plugins/network-manager/edr/edr-provider.ts	Migrates EDR provider logger to `createDebug`.
packages/hardhat/src/internal/builtin-plugins/gas-analytics/gas-analytics-manager.ts	Migrates gas analytics debug logger to `createDebug`.
packages/hardhat/src/internal/builtin-plugins/coverage/hook-handlers/solidity.ts	Migrates coverage hook handler logger to `createDebug`.
packages/hardhat/src/internal/builtin-plugins/coverage/coverage-manager.ts	Migrates coverage manager logger to `createDebug`.
packages/hardhat/src/internal/builtin-plugins/console/task-action.ts	Migrates console task logger to `createDebug`.
packages/hardhat/package.json	Drops `debug` and `@types/debug` dependencies.
packages/hardhat-verify/src/internal/metadata.ts	Migrates verify metadata logger to `createDebug`.
packages/hardhat-verify/src/internal/etherscan.ts	Migrates etherscan logger to `createDebug`.
packages/hardhat-verify/src/internal/blockscout.ts	Migrates blockscout logger to `createDebug`.
packages/hardhat-verify/package.json	Drops `debug` and `@types/debug` dependencies.
packages/hardhat-vendored/package.json	Drops `@types/debug` devDependency.
packages/hardhat-utils/test/debug.ts	Adds unit tests for `createDebug` + pattern parsing + color behavior.
packages/hardhat-utils/src/synchronization.ts	Migrates mutex logging to use the in-package `createDebug`.
packages/hardhat-utils/src/internal/debug.ts	Introduces internal helpers for pattern parsing, enable checks, and color selection.
packages/hardhat-utils/src/debug.ts	Implements `createDebug` and defines the exported `DebugLogger` type.
packages/hardhat-utils/package.json	Drops `debug` and `@types/debug` dependencies.
packages/hardhat-typechain/src/internal/generate-types.ts	Migrates typechain logger to `createDebug`.
packages/hardhat-typechain/package.json	Drops `debug` and `@types/debug` dependencies.
packages/hardhat-solx/src/internal/hook-handlers/solidity.ts	Migrates solx hook handler logger to `createDebug`.
packages/hardhat-solx/src/internal/hook-handlers/config.ts	Migrates solx config hook logger to `createDebug`.
packages/hardhat-solx/src/internal/downloader.ts	Migrates solx downloader logger to `createDebug`.
packages/hardhat-solx/package.json	Drops `debug` and `@types/debug` dependencies.
packages/hardhat-network-helpers/package.json	Drops `@types/debug` devDependency.
packages/hardhat-mocha/src/task-action.ts	Migrates performance logger to `createDebug`.
packages/hardhat-mocha/package.json	Drops `debug` and `@types/debug` dependencies.
packages/hardhat-ledger/src/internal/handler.ts	Migrates ledger handler logger to `createDebug`.
packages/hardhat-ledger/package.json	Drops `debug` and `@types/debug` dependencies.
packages/hardhat-keystore/src/internal/hook-handlers/config.ts	Migrates keystore config hook logger to `createDebug`.
packages/hardhat-keystore/package.json	Drops `debug` and `@types/debug` dependencies.
packages/hardhat-ignition/src/internal/utils/load-module.ts	Migrates ignition module loader logger to `createDebug`.
packages/hardhat-ignition/package.json	Drops `debug` and `@types/debug` dependencies.
packages/hardhat-ethers/src/internal/hardhat-ethers-provider/hardhat-ethers-provider.ts	Migrates ethers provider logger to `createDebug`.
packages/hardhat-ethers/package.json	Drops `debug` and `@types/debug` dependencies.
packages/hardhat-ethers-chai-matchers/package.json	Drops `@types/debug` devDependency.
.changeset/full-otters-say.md	Adds a changeset describing the performance improvement and patch bumps.

Files not reviewed (1)

pnpm-lock.yaml: Language not supported

schaable added 6 commits April 24, 2026 20:25

Add createDebug logger factory to hardhat-utils

44de9a8

Add tests for createDebug

99cd2cc

Performance optimizations

5c62aec

Replace debug package with createDebug across packages

b01c94b

add changeset

fad5a2a

Expand createDebug palette to 49 colours

dadc2fa

schaable self-assigned this Apr 25, 2026

Copilot AI review requested due to automatic review settings April 25, 2026 18:25

schaable added no docs needed This PR doesn't require links to documentation no peer bump needed labels Apr 25, 2026

Copilot started reviewing on behalf of schaable April 25, 2026 18:26 View session

Copilot AI reviewed Apr 25, 2026

View reviewed changes

Comment thread packages/hardhat-utils/src/debug.ts

Comment thread pnpm-lock.yaml

schaable mentioned this pull request Apr 25, 2026

Normalize debug namespaces across packages #8193

Merged

alcuadrado approved these changes Apr 27, 2026

View reviewed changes

schaable added this pull request to the merge queue Apr 27, 2026

Merged via the queue into main with commit db86e58 Apr 27, 2026
310 checks passed

schaable deleted the replace-debug branch April 27, 2026 17:39

github-actions Bot mentioned this pull request Apr 27, 2026

Version Packages (v3) #8198

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Replace `debug` package with in-tree `createDebug` helper#8192

Replace `debug` package with in-tree `createDebug` helper#8192
schaable merged 6 commits intomainfrom
replace-debug

schaable commented Apr 25, 2026 •

edited

Loading

Uh oh!

changeset-bot Bot commented Apr 25, 2026

Uh oh!

github-actions Bot commented Apr 25, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

schaable commented Apr 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Overview

Differences against debug

Tests

Benchmark

Uh oh!

changeset-bot Bot commented Apr 25, 2026

🦋 Changeset detected

Uh oh!

github-actions Bot commented Apr 25, 2026

hardhat

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

schaable commented Apr 25, 2026 •

edited

Loading

Differences against `debug`