Introduction

Tame the JS console by automagically grouping console messages.

• Simple: Drop in replacement for the full console API.
• Automatic: Groups messages by each Event Loop iteration.
• Easier Debugging: Makes it much clearer to see what is going on in your app.
• Adds Time Stamps: Each grouping can be timestamped, to help better see what is happening.
• Reliable: Uses a Microtask to ensure the message group is always closed on time.

A more readable console output in a couple of minutes.

Above created by example.ts.

Install

Install auto-console-group via npm.

npm install auto-console-group

Setup

The createAutoConsoleGroup() creates a console object with all the same methods as the regular console object, plus a few additional methods to control how a group is displayed.

import createAutoConsoleGroup from 'auto-console-group'

const consoleGroup = createAutoConsoleGroup({ label: 'autoConsoleGroup' })

// All console methods are reflected on consoleGroup
consoleGroup.log('Log message')
consoleGroup.table(['foo', 'bar'])
consoleGroup.count('Counter')

// Set the Event in the group heading
consoleGroup.event('myEvent')

Group Heading

The heading for each group is made up of three parts: Label, Event and Time.

Label

The first part of the heading is the label, and is for showing your library or application name. The label is set via the options when you create a consoleGroup.

Event

The second part, shown in bold, is the Event. This is for indicating the trigger for the current event loop. The event heading for the current loop is set via the .event() method for the current event loop. After which it will automatically reset to the defaultEvent which is set in the options.

const consoleGroup = createAutoConsoleGroup({ options })

consoleGroup.event('myEvent')

Time

Optionally the group heading can included the time of the first logged message. To disable this function set the showTime option to false.

Options

The following options can be passed to createAutoConsoleGroup.

{
  label: 'Label',          // First part of the group heading
  collapsed: false,        // Show groups expanded or collapsed
  defaultEvent: 'Event',   // Second part of the group heading, shown in bold
  showTime: true,          // Display time in the group headings
}

When the collapsed option is set to true, the group will automatically open if a warning or error is included in the group.

Error Boundaries

This library works by storing console messages in an array and outputting the collected list of messages via a microtask that runs directly after the main Event Loop task completes, and will continue to work even in the event of a runtime error; however, as the microtask runs after the main task has terminated, the current log group will be displayed after the error, rather than in front of it.

To overcome this limitation, you can create an Error Boundary, which will catch runtime errors and included them in the current console group.

const consoleGroup = createAutoConsoleGroup({ label: 'Error boundary example' })

consoleGroup.errorBoundary(() => {
  consoleGroup.log('Message before error')
  throw new Error('Runtime error')
})

Methods

In addition to the full Console API, the following methods are also available.

endAutoGroup()

Force the current group to output to the browser console. Any logs created after this call will appear in a new group.

errorBoundary(Function)

Create an error boundary around a function. This allows auto-console-group to display runtime errors within the console group.

event(String)

Set the event type part of the group heading for just the current event loop iteration.

purge()

Remove all messages in the current output queue.

Helpers

To assist with colouring console messages, the package also contains two consts that will return the current hex codes for highlighting log message.

HIGHLIGHT

The default console highlight colour, based on dark/light mode.

FOREGROUND

The current console foreground colour, based on dark/light mode.

---

© 2025 David J. Bradshaw - License MIT