Native logging for your NPM package

When working with nodejs, if you are coding a NPM package, you might want to keep your package light but with basic logging.

One use-case could be you want your package to have 0 dependency, but allow the package's users to enable logs only when they need it. By default, any console.* in the code will appear in the output.

There is a native nodejs way with the util package, and especially the debuglog function.

Let's have a look to a simple example:

// ./index.js
const log = require('node:util').debuglog('foo')
log('starting package!')

This won't show any output unless you run it with the correct flag:

NODE_DEBUG=foo node index.js.

When debugging, you can add the flag NODE_DEBUG=foo to your NPM scripts (such npm run dev) to see all outputs. Make sure to let your users know, in order for them to see the logs when using/debugging the package.

There is as well a wildcard mode to match all custom logging you could create:

// index.js - node v18.11.0
const util = require('node:util')
const log = {
  network: util.debuglog('foo-network'),
  verbose: util.debuglog('foo-verbose')
  // <-- extend it to improve your logging!
}

log.verbose('starting package!')

new Promise(resolve => setTimeout(resolve, 2000))
  .then(_ => log.network('network call done'))

With the following outputs:

~ ❯ NODE_DEBUG=foo* node index.js
FOO-VERBOSE 23347: starting package!
FOO-NETWORK 23347: network call done

~ ❯ NODE_DEBUG=foo-network node index.js
FOO-NETWORK 23400: network call done
~ ❯

1st time was run with the wildcard on. And the 2nd time, in an imaginary scenario where the user would only need the NETWORK logs.

It is a good practice to namespace the section you pass to debuglog with your package name toallow granular debuging.

Fun fact, if you run a nodejs script with all debug logs activated (NODE_DEBUG=*), you can get more information on your script:

~ ❯ NODE_DEBUG=* node index.js
MODULE 23530: looking for "/Users/francois/index.js" in ["/Users/francois/.node_modules","/Users/francois/.node_libraries","/usr/local/Cellar/node/18.11.0/lib/node"]
MODULE 23530: load "/Users/francois/index.js" for module "."
MODULE 23530: Module._load REQUEST node:util parent: .
MODULE 23530: load built-in module node:util
FOO-VERBOSE 23530: starting package!
TIMER 23530: no 2000 list was found in insert, creating a new one
TIMER 23530: process timer lists 2087
TIMER 23530: timeout callback 2000
TIMER 23530: 2000 list empty
FOO-NETWORK 23530: network call done

ℹ️ Tip 1: if you need more options like adding colors, have a look to the debug package.

ℹ️ Tips 2: util.debuglog has an alias with util.debug! 😎