Consola: Replacing console.log with structured logging and automatic environment detection

How Consola routes output through reporters

Consola intercepts log calls and passes them to one or more reporters. You call consola.info or consola.success, and Consola routes that call to every registered reporter. The default reporter wraps text in ANSI color codes and adds emoji: consola.success outputs a checkmark, consola.error a red X, consola.warn a yellow triangle. In CI and testing environments, Consola auto-detects the context using unjs/std-env and switches to a basic reporter that strips colors and emoji but preserves the message structure.

Reporters are swappable. Browsers receive a simple reporter that outputs to the JavaScript console. Log messages are filtered by log level before they reach any reporter: levels range from 0 (fatal and error only) through 5 (including trace), with 3 as the default. Set the level via the CONSOLA_LEVEL environment variable, consola.level, or the createConsola option.

Consola ships three entry points to control bundle size. The default import includes all reporters; consola/basic has only the basic reporter; consola/browser is for the browser; consola/core provides no reporters at all. The core build shaves 80% off the size.

Installing and logging your first message

Install consola with npm:

npm i consola

Import the default instance and start logging:

import { consola } from "consola";

consola.info("Using consola 3.0.0");
consola.start("Building project...");
consola.warn("A new version of consola is available: 3.0.1");
consola.success("Project built!");
consola.error(new Error("This is an example error. Everything is fine!"));
consola.box("I am a simple box");
await consola.prompt("Deploy to the production?", {
  type: "confirm",
});

In CommonJS modules, use require:

const { consola } = require("consola");

Consola detects your environment and auto-selects the reporter. In development you see colors and emoji; in CI or tests, plain text. To create a new instance with custom settings instead of using the global one:

import { createConsola } from "consola";

const logger = createConsola({
  // level: 4,
  // fancy: true | false
  // formatOptions: {
  //     columns: 80,
  //     colors: false,
  //     compact: false,
  //     date: false,
  // },
});

Pass level: 4 to enable debug logging, or fancy: false to strip colors.

Reporters and custom output

Reporters are objects with a log method that receives a log object. The default reporter writes to stdout or stderr based on log level. You can add, remove, or replace reporters entirely.

Create a custom reporter that outputs JSON:

import { createConsola } from "consola";

const consola = createConsola({
  reporters: [
    {
      log: (logObj) => {
        console.log(JSON.stringify(logObj));
      },
    },
  ],
});

consola.log("foo bar");

Your reporter receives the full log object, which carries type (info, warn, error, etc), level (0-5), args, date, and tag. Consola calls your reporter for every log at or below the configured level. You can route logs to a file, a network service, or another destination in the reporter.

Call addReporter (alias add) to register a custom reporter instance alongside the default reporters. Call removeReporter (aliases remove or clear) to remove a registered reporter. If no arguments are passed to removeReporter, all reporters are removed. Call setReporters to replace all reporters with your own set.

Tags and multiple loggers

Create a tagged logger for a module with consola.withTag, which creates a new Consola instance with that tag. The withScope alias does the same. Tags appear in the log output, and the reporter receives the tag in the log object. You can also use withDefaults to create a new instance with provided defaults, then use withTag on that instance to add both defaults and a tag.

Wrapping and redirecting system output

Consola can intercept and redirect console calls, stdout, and stderr. Call wrapConsole to globally replace console.log, console.info, console.error and similar with consola handlers.

Call wrapStd to globally redirect process.stdout and process.stderr through consola.

Call wrapAll to wrap both console and std in one call. Console uses std underneath, so calling wrapStd redirects console too; wrapAll ensures things like console.info are correctly redirected to the corresponding type.

To restore the original behavior, call restoreConsole, restoreStd, or restoreAll. Wrapping is global and affects all modules that use console or std after the call. This is useful in application startup to funnel all output through one logger.

Interactive prompts and mocking

Consola can show input prompts powered by the clack library. The prompt method takes a message and an options object with type: text, confirm, select, or multiselect. If the user cancels with Control+C, the promise resolves with the default value by default; configure the cancel option to reject instead or resolve with null or a symbol.

For testing, mock all log types at once:

// Jest
consola.mockTypes((typeName, type) => jest.fn());
// Vitest
consola.mockTypes((typeName, type) => vi.fn());

The callback receives the type name and the type object and returns the mock function. Return a falsy value to skip mocking a type. This is useful in test suites to suppress noise and assert that your code calls the right log methods. Any instance of consola that inherits the mocked instance will apply the callback again, so mocking works for withTag scoped loggers without extra effort.

Log types and pausing logs

Consola provides typed log methods like consola.success, consola.warn, consola.ready, consola.start, consola.fail. Each has a preset log level and formatting. The full list is in src/constants.ts in the repository.

Call pauseLogs or its alias pause to globally pause all logging. Logged messages are enqueued while paused. Call resumeLogs or its alias resume to send all enqueued logs to reporters. This is useful when you want to silence output during a test setup phase and then see everything at the end.

When Consola is the wrong choice

Consola is not optimized for high-throughput logging in production services. All reporters run synchronously for every log call, so a slow custom reporter blocks the calling code. If you need to write millions of logs per second, or route logs to an external service without blocking, Consola's architecture will slow you down. Pino and winston solve this with asynchronous reporters and buffering.

Consola also does not provide structured JSON logging as a first-class feature. The default output is human-readable text with emoji and colors, which is the opposite of what production systems usually want. You can build a JSON reporter and attach it, but that is optional and not the expected usage. If you are running an API server that ships logs to a logging aggregation service, Consola adds an extra layer of formatting you will need to parse back out.

Consola compared to pino

The search data shows people ask about consola versus pino. Pino focuses on structured JSON logging and is built for high-performance servers where every byte matters; it has one format and no reporters. Consola is broader: it emphasizes visual output for CLI tools and development, supports multiple reporters and log levels in a single instance, and automatically adapts formatting to the environment. Pino suits production services that ship logs to external systems; Consola suits CLI tools and development servers where you read logs in the terminal. Both are zero-dependency libraries, but they solve different problems. If you are building a CLI tool, Consola is more likely the right choice. If you are running a high-volume API server, Pino's structure and performance are a better fit.

Editorial conclusion

Consola suits teams building CLI tools or Node servers that need better structured logging than native console. It is most useful where you want consistent formatting across development and testing environments, since it auto-detects CI and testing contexts and scales output accordingly. The reporter system lets you route logs to files or external services. Start by importing consola and replacing console.log calls with consola.info or consola.success; if the defaults do not fit, write a custom reporter before you fork the architecture.

Frequently asked questions

Official sources

1. Issues
2. README
3. Releases
4. unjs/consola on GitHub