@bicycle-codes/debug

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
• example
  • browser
  • node JS
• develop
  • browser
  • node

install

npm i -D @bicycle-codes/debug

Use this with vite in the browser or in node.

example

browser

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

VITE_DEBUG=fooo

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

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

a third config option

You can pass in an env variable of VITE_DEBUG_MODE, and then debug will check for that mode in vite.

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 '@bicycle-codes/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 '@bicycle-codes/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 '@bicycle-codes/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 '@bicycle-codes/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 shoudlLog function:

// in node only
import Debug from '@bicycle-codes/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

Changelog

v0.7.2 - 2024-11-12

Commits

• tweak types a1478c7