@substrate-system/debug
    Preparing search index...

    @substrate-system/debug

    debug

    tests module types semantic versioning install size GZip size license

    • [x] Cloudflare
    • [x] Node
    • [x] browsers

    A tiny JavaScript debugging utility that works in Node and browsers. Use environment variables to control logging in Node, and localStorage in browsers. Keep your ridiculous console log statements out of production.

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

    In the browser, this uses localStorage key 'DEBUG'. In Node, it uses the environment variable DEBUG.

    Featuring:

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

    Plus, see the docs generated by typescript.

    npm i -D @substrate-system/debug

    Browser usage: Use localStorage DEBUG key. Node.js usage: Use environment variable DEBUG.

    In the browser, this looks for the DEBUG key in localStorage.

    import Debug from '@substrate-system/debug'

    // Set DEBUG in localStorage
    localStorage.setItem('DEBUG', 'myapp:*')

    // create debug instance
    const debug = Debug('myapp:component')
    debug('hello logs')
    // will log, because DEBUG in localStorage matches 'myapp:component'

    Use dynamic imports to keep this entirely out of production code, so your bundle is smaller.

    Either build this module to the right path, or copy the bundled JS included here, then you can dynamically import the module.

    cp ./node_modules/@substrate-system/debug/dist/browser/index.min.js ./public/debug.js
    Note


    We export noop here; it has the same type signature as debug.

    import { type Debug, noop } from '@substrate-system/debug/noop'

    let debug:ReturnType<typeof Debug> = noop
    if (import.meta.env.DEV) {
      const Debug = await import('/example-path/debug.js')
      debug = Debug('myApplication:abc')
    }

    Or use the HTML importmap script tag to replace this in production. In these examples, you would need to build this module or copy the minified JS file to the right directory, so it is accessible to your web server.

    <script type="importmap">
    {
      "imports": {
        "@substrate-system/debug": "/example-path/debug.js",
      }
    }
    </script>

    <script type="importmap">
    {
      "imports": {
        "@substrate-system/debug": "data:text/javascript,export default function(){return()=>{}}"
      }
    }
    </script>
    Tip

    Using a data: URL means no network request at all for the noop.

    Either pass in an env record, or will look at globalThis for the DEBUG variable.

    import Debug from '@substrate-system/debug/cloudflare'

    const myEnvVar = {
      DEBUG: 'abc:*'
    }

    const debug = Debug('abc:123', myEnvVar)

    Run your script with an env variable, DEBUG.

    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

    In browsers, this checks localStorage for DEBUG key. In Node.js, this checks the environment variable DEBUG.

    import Debug from '@substrate-system/debug'

    // In browser: checks localStorage.getItem('DEBUG')
    const debug = Debug('example')

    // Log if no namespace is set in localStorage
    const debug = Debug(import.meta.env.DEV)

    localStorage.setItem('DEBUG', '*')

    localStorage.setItem('DEBUG', 'myapp:auth,myapp:api,myapp:api:*')

    Pass in a boolean to enable or disable the debug instance. This will log with a random color.

    import Debug from '@substrate-system/debug'
    const debug = Debug(import.meta.env.DEV)  // for vite dev server

    debug('hello')
    // => DEV hello

    You can extend the debugger to create new debug instances with new namespaces:

    const log = Debug('auth')

    // Creates new debug instance with extended namespace
    const logSign = log.extend('sign')
    const logLogin = log.extend('login')

    window.localStorage.setItem('DEBUG', 'auth,auth:*')

    log('hello')  // auth hello
    logSign('hello')  // auth:sign hello  
    logLogin('hello')  // auth:login hello

    Chained extending is also supported:

    const logSignVerbose = logSign.extend('verbose')
    logSignVerbose('hello')  // auth:sign:verbose hello

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

    npm start

    npx esbuild --platform=node --bundle ./example/node.ts | DEBUG="hello:*" node

    Try it with a different env var to see different logs:

    npx esbuild --platform=node --bundle ./example/node.ts | DEBUG="hello:*,abc123:*" node

    or

    npm run example:node

    npm test

    npm run test:node

    npm run test:cloudflare

    npm run test:browser

    Settings

    Member Visibility

    On This Page

    debug