substrate-system/debug

Debug utility

debug

A tiny JavaScript debugging utility that works in Node.js and browsers. Use environment variables to control logging, so there are no ridiculous console log statements in production.

This is based on debug. It's been rewritten to use contemporary JS.

Featuring:

• Use exports field in package.json to choose node JS or browser version
• ESM only

Plus, see the docs generated by typescript.

Contents

• install
• TL;DR
• configure
• example
  • browser
  • Node JS
• develop
  • browser
  • node

install

npm i -D @substrate-system/debug

Use this with vite in the browser, or in node.

---

TL;DR

There are two env variables to work with, VITE_DEBUG and VITE_DEBUG_MODE in the browser, and DEBUG and NODE_ENV in node.

To determine if we should log something, first we check NODE_ENV / VITE_DEBUG_MODE. By default, in the browser we check import.meta.env.DEV, and in node, NODE_ENV should be either development or test. But -- you can configure this.

Next we check the namespace + the env variable VITE_DEBUG in the browser, and DEBUG in node.

If the DEBUG/VITE_DEBUG variable is not set and you are in dev mode, then we log. If the DEBUG/VITE_DEBUG variable is set, then we only log if it matches the namespace that was passed in to debug, i.e.

import Debug from '@substrate-system/debug'
const debug = Debug('hello-123')

debug('hello world')

The character * is a wildcard. In the preceding example, 'hello world would be logged if we started vite with either VITE_DEBUG=hello-* or VITE_DEBUG=hello-123.

---

configure

Set the property shouldLog on Debug to configure which modes we log in. In the browser, this function gets called with import.meta.env.MODE. In node, it is called with process.env.NODE_ENV.

import Debug from '@substrate-system/debug'
Debug.shouldLog = (envString) => {
  return (envString === 'staging' || import.meta.env.DEV)
}

example

browser

This is ergonomic with the vite bundler. This module will look for an env variable prefixed with VITE_:

VITE_DEBUG=fooo

Given then above env variable in vite, you would log like this:

import Debug from '@substrate-system/debug'
const debug = Debug('fooo')
debug('hello fooo')

*

Use an environment variable of * to log everything.

VITE_DEBUG="*"

DEV mode

If you initialize this without a namespace, then it checks import.meta.env.DEV:

import Debug from '@substrate-system/debug'
const debug = Debug()
debug('debug works')   // check if `import.meta.env.DEV`

For example, in the staging environment:

VITE_DEBUG_MODE=staging vite build --mode staging

use multiple modes

Can parse a comma separated list of modes.

A .env file like this:

VITE_DEBUG_MODE="test, staging"

Will log in either "test" or "staging" modes, or if import.meta.env.DEV is true.

vite --mode staging build

If you are in production (import.meta.env.PROD) and there is no VITE_DEBUG env var, then this exports a noop, so debug will do nothing, and your bundle will be smaller.

Use a namespace

In your JS code:

import { createDebug } from '@substrate-system/debug'
const debug = createDebug('fooo')
debug('debug works')

You would start that script with a VITE_DEBUG=fooo env var to see the log statements.

Don't use a namespace

If you call this without a namespace argument, it will look at the value of import.meta.env.DEV. If you are in DEV mode, then it will log things in a random color:

import { createDebug } from '@substrate-system/debug'
const debug = createDebug('fooo')
const debug2 = createDebug()

debug('debug works')
debug2('testing debug 2')
setTimeout(() => {
    debug2('log again')
}, 1000)

Node JS

Run your script with an env variable, DEBUG.

// in node JS
import createDebug from '@substrate-system/debug/node'
const debug = createDebug('fooo')
debug('testing')

Call this with an env var of DEBUG=fooo

DEBUG=fooo node ./test/fixture/node.js

NODE_ENV

If you are in dev mode (process.env.NODE_ENV === 'development'), then this will log things in a random color if you don't initialize it with a namespace --

import createDebug from '@substrate-system/debug'
const debug = createDebug()
debug('hello')

Run the script like this:

NODE_ENV=development node ./my-script.js

Configure the environment value

Configure what NODE_ENV value will trigger logging by overriding the shouldLog function:

// in node only
import Debug from '@substrate-system/debug'

Debug.shouldLog = function (NODE_ENV) {
    return NODE_ENV === 'example'
}
const debug = Debug()
// this will log iff we start this like
// NODE_ENV="example" node my-program.js
debug('testing')

---

develop

browser

Start a vite server and log some things. This uses the example directory.

npm start

node

Run tests:

npm test