Adze JS - Better JavaScript Logging

# Installing Adze

WARNING

Adze v1.x is now deprecated! Please upgrade to v2.x (opens new window)!

# Install the Package

You can install Adze from NPM using the following command:

# NPM
npm install --save adze

# Yarn
yarn add adze

# Version Requirements

Dependency Supported Versions Notes
node >= 10.x When running Adze in a Node environment.
typescript >= 4.1 When using Adze with TypeScript

# TypeScript Configuration

Adze is built to be used with TypeScript and we highly encourage using it in this way.

When building your project with TypeScript, you need to make sure you use the "DOM" lib because Adze supports both the web browser and Node. Also, to support the dependencies of Adze, you'll need to add "esModuleInterop": true to your tsconfig as well.

For more information about configuring TypeScript, go to https://www.typescriptlang.org/docs/handbook/tsconfig-json.html (opens new window).

# Example

{
  "compilerOptions": {
    // ...your other options
    "lib": ["DOM"],
    "esModuleInterop": true
  }
}

# Importing Adze

Adze comes bundled with a few different ways of accessing it. Here are some examples:

# CDN

You can import the library directly into your HTML from the jsDelivr (opens new window) CDN.

NOTE: In the script tag in the example below, replace <version> with the version of Adze you would like to use.

<!-- In the head of your html -->
<head>
  <!-- To use v1.4.0 you would write https://cdn.jsdelivr.net/npm/adze@1.4.0/dist/adze.min.js -->
  <script src="https://cdn.jsdelivr.net/npm/adze@<version>/dist/adze.min.js"></script>
</head>

<!-- Using adze elsewhere in JS -->
<script>
  // Adze is registered globally in your browser as AdzeLib
  const { adze } = AdzeLib;

  adze().log('Hello World!');
</script>

# Node JS (CommonJS)

const { adze } = require('adze'); // Or alternatively `const adze = require('adze').adze;`

adze().log('Hello World!');

# ES6 / TypeScript

import adze from 'adze';

adze().log('Hello World!');

# Line Numbers / Blackboxing

Although Adze is meant primarily for long-lived logs that should be in production environments you can use it for debugging purposes just like the standard console API. The caveat with using it for debugging is that you will need to enable Blackboxing (opens new window).

A common problem with libraries that wrap the standard console API is that they lose line numbers in the browser console. This occurs because the browser console is reporting the line number at which the console API was called, which is usually within the library wrapper. To get around this problem, Chromium based browsers (like Chrome, Edge and Brave) added the Blackboxing (opens new window) concept. This tells the browser to pretend like the library source code doesn't exist. This enables Adze logs to print correct line numbers from where they are called.

For information on setting up Blackboxing, please go to https://bit.ly/3d1eOex (opens new window).

NOTE: The verbiage for this has been changed to Ignore List in the console settings.

To blackbox the adze library you will need to supply the following regular expression:

/\b(?:util|BaseLog)\b\.js/g

For non-chromium based browsers, right now there is no easy way to work around this issue. We suggest using the standard console API for debugging purposes where line numbers are important and reserving Adze logs for long-lived logs that will be used in production environments.

← Adze Concepts →