Debug Output

While working in different stages like development or even production it may be useful to switch on and off debug statements on demand.

This is done through a tiny NodeJS debug utility modelled after node core´s debugging technique. It can be enabled through environment settings and will printout some predefined messages. Another small helper called chalk to make the output messages color full.

A lot of foreign libraries are also using debug so it will work on their code also.

1. Installation

Because this should also stay in the productive code

npm install debug chalk --save

2. Usage

Simply create a debug instance by giving it the name of your module and maybe the subroutine as concatenated function. Using it´s debug method will return a decorated version of the given message to console.error only if debug is enabled.

import Debug from 'debug'

// initialize debug with module name and maybe sub element
const debug = Debug('<module>')('<sub>')

debug('new instance created using %o', setup)

You may also make the output colorful by also adding the earlier mentioned chalk module:

import Debug from 'debug'
import chalk from 'chalk'

// initialize debug with module name and maybe sub element
const debug = Debug('<module>')('<sub>')

debug(chalk.red('new instance created using %o'), setup)

Code to run only if enabled

if (debug.enabled) {
  debug(claculateMessage())
}

This allows to only run the message calculation if debugging is enabled for this module.

Formatters

Debug uses printf-style formatting supporting the following formatters:

Debug names

The convention is to use the short name of the module as debug name like config for the alinex-config module. The sub names are often used after their file names which implies the functional part like config:compile for the compiler class in compile.js.

Also within the tests you may use test as debug module name.

3. Colors

The debug module already uses colors if possible for the namespace identifier. It will try to pick a different color for each namespace to make it easier to overflow a bigger output. But like described above you may use chalk yourself to make the message itself also colorful. Possible colors are:

• red, bold.red
• green, bold.green
• yellow, bold.yellow
• blue, bold.blue
• magenta, bold.magenta
• cyan, bold.cyan
• white, bold.white
• gray, bold.gray
• black, bold.black

The bold versions resemble the color more. But you may also combine this with dim, italic, underline, inverse, strikethrough and also set bgRed...

4. Control debugging

When running the code, you can set a few environment variables that will change the behavior of the debug logging:

For the DEBUG variable, you can give multiple comma separated namespaces using colon as delimiter between the namespace levels. An * character is also possible to select multiple or all: