CLI tool
unjs/consola avatar
unjs/consola

unjs/consola: three slim builds, one log level, and a mock that propagates

🐨 Elegant Console Logger for Node.js and Browser

7,350 stars230 forksTypeScriptNOASSERTION

At a glance

What is it?
consola is a console wrapper for Node and browsers whose selling points are a fancy reporter with a fallback, pluggable reporters, throttling, prompts and a mocking mode for tests. Two mechanisms are less obvious than the feature list: the log level can arrive from an environment variable, except in the browser and core builds, and mocking a type applies to every instance that inherits the mocked one, which is what makes tagged loggers work without extra setup.
Who is it for?
consola fits a project that wants one logging call that looks the same in a terminal, a test run and a browser tab, and that needs tags and prompts without pulling in a large logging framework. It does not fit someone who needs structured logging to a transport, since the built-in reporters write to the console and anything else is a reporter you write.
Can I use it commercially?
Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
Is it still maintained?
Yes. The repository last received commits 1 day ago.
What is it written in?
Mainly TypeScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 16, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • unjs/consola7,350 ★ · +21
Star history
Repository2026-09-232026-11-16
unjs/consola7.3k7.4k

21 Stars in the last 54 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The log level defaults to 3 and has three ways in

Consola shows only logs at or below its configured level, and the default is 3. The scale runs from 0 for fatal and error, 1 for warnings, 2 for normal logs, 3 for informational logs and the success, fail, ready and start family, 4 for debug, and 5 for trace, with -999 meaning silent and +999 meaning verbose. Three mechanisms set it: the `level` option passed to `createConsola`, the `level` property on an instance, or the `CONSOLA_LEVEL` environment variable. That last one has a limitation stated in the readme: it is not supported for the browser and core builds, so the same configuration behaves differently depending on which entry point your bundle resolved.

Three entry points, and the basic build saves 80%

The package publishes more than one surface. Alongside the main entry there is a browser entry, a basic entry and a core entry, and the readme frames the smaller builds as ones without the fancy reporter that save 80% of the bundle size:

ts
import { consola, createConsola } from "consola/basic";
import { consola, createConsola } from "consola/browser";
import { createConsola } from "consola/core";

The manifest shows how carefully this is mapped. The main entry has separate branches for Node and for everything else, each splitting again by import and require, so a Node CommonJS consumer receives a file from a `lib` directory while an ESM consumer receives one from `dist`. The basic entry repeats that shape, while the browser entry splits only by import and require, each with types under dist. Four declaration files sit at the repository root: basic.d.ts, browser.d.ts, core.d.ts and utils.d.ts.

wrapStd already redirects console, and wrapAll exists for typing

There are three pairs of wrapping functions, and their relationship is the interesting part. `wrapConsole` and `restoreConsole` redirect `console.log` and the rest to consola handlers. `wrapStd` and `restoreStd` redirect standard output and standard error. `wrapAll` and `restoreAll` do both, but the readme explains that console is implemented on top of standard output underneath, so calling `wrapStd` alone already redirects console as well. What `wrapAll` adds is correct typing: because `console.info` is then routed to the corresponding log type rather than flattened, a log that was an info becomes an info in the output instead of a plain log.

pauseLogs queues everything and resumeLogs flushes it

Two methods, aliased to `pause` and `resume`, pause and resume logging globally. The behaviour while paused is buffering rather than discarding: consola enqueues all logs and sends them to the reporters once resumed. That makes it a poor fit for suppressing noise and a good fit for tests that assert on output, since nothing emitted during the pause window is lost. Both operations are global rather than per instance, which is the one limitation to keep in mind in a codebase with several loggers: pausing one instance's output affects every instance built from the same global consola.

A mocked type propagates into every derived instance

Mocking exists for tests, and the callback receives the type name and the type object:

js
// Jest
const fn = jest.fn();
// Vitest
const fn = vi.fn();
consola.mockTypes(() => fn);

Two rules govern the result. If the callback returns a falsy value, that type is not mocked at all, which is how you mock a single type such as `fatal` by returning a mock only for that name. And the note that matters most for structure: any instance of consola that inherits the mocked instance applies the callback again. That is deliberate, and it is what makes mocking work for tagged loggers created with `withTag` without extra configuration, since a scoped instance re-runs the callback rather than bypassing it.

A reporter is one method, and the default changes in CI

Custom reporters implement an interface with a single method that receives the log object, and the readme's first example is a reporter that stringifies it to JSON. The second example shows the shape you would use to make a fatal log exit the process, which is the pattern for turning logging into process control. Three reporters ship by default: a fancy coloured one, a basic one that the fancy reporter falls back to when a testing or continuous integration environment is detected through a separate package for environment detection, and a basic browser reporter. That fallback is automatic, which means the same code produces readable output locally and plainer output in a pipeline without any configuration.

The newest release is from March 2025 while the branch keeps moving

Release history and commit history diverge here. The three most recent tags are v3.4.0 on 2025-01-13, v3.4.1 on 2025-03-17 and v3.4.2 on 2025-03-18, so two of them landed on consecutive days, and the manifest still reports 3.4.2. The repository was pushed to on 2026-10-30, more than nineteen months after the newest tag. Dependency upkeep appears to be automated, since a Renovate configuration sits at the root, and the examples directory is unusually large for a logger: separate files for wrapping each target, for mocking, pausing, throttling, prompts in both module systems, JSON output, spinner, tree and box rendering, plus an HTML page and a legacy variant of it.

Editorial conclusion

consola fits a project that wants one logging call that looks the same in a terminal, a test run and a browser tab, and that needs tags and prompts without pulling in a large logging framework. It does not fit someone who needs structured logging to a transport, since the built-in reporters write to the console and anything else is a reporter you write. Before adopting it, decide which entry point you import, because the environment variable for the log level is ignored in the browser and core builds, and set the level explicitly if you rely on it.

Frequently asked questions

What is consola?

consola is an MIT licensed console wrapper for Node.js and the browser. It ships a fancy reporter with a fallback for minimal environments, pluggable reporters, tag support, prompts powered by clack, log throttling, and a mocking mode for tests.

How do I change the consola log level?

Pass the level option to createConsola, set the level property on an instance, or use the CONSOLA_LEVEL environment variable. The default is 3, and the environment variable is not supported in the browser and core builds.

How do I mock consola in jest or vitest?

Pass a callback to mockTypes, which is aliased to mock, receiving the type name and type and returning the mock. Returning a falsy value leaves that type unmocked, and any consola instance inheriting the mocked one applies the callback again.

Official sources

  1. Issues
  2. README
  3. Releases
  4. unjs/consola on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/unjs-consola.svg)](https://hysenlabs.com/projects/unjs-consola)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/unjs-consola.svg)](https://hysenlabs.com/projects/unjs-consola)

Was this useful?