@docusaurus/logger

What is @docusaurus/logger?

@docusaurus/logger is a logging utility designed for use with Docusaurus, a popular static site generator. It provides a simple and consistent way to log messages with different levels of severity, such as info, warn, error, and success. The package is useful for developers who need to output logs during the build process or while running scripts related to Docusaurus projects.

What are @docusaurus/logger's main functionalities?

Info Logging

Logs an informational message. This is useful for general-purpose logging to inform the user about the progress or state of the application.

const logger = require('@docusaurus/logger');
logger.info('This is an info message');

Warning Logging

Logs a warning message. This is useful for indicating potential issues that are not critical but should be noted.

const logger = require('@docusaurus/logger');
logger.warn('This is a warning message');

Error Logging

Logs an error message. This is useful for reporting errors that occur during the execution of the application.

const logger = require('@docusaurus/logger');
logger.error('This is an error message');

Success Logging

Logs a success message. This is useful for indicating successful completion of tasks or operations.

const logger = require('@docusaurus/logger');
logger.success('This is a success message');

Other packages similar to @docusaurus/logger

winston

Winston is a versatile logging library for Node.js that supports multiple transports (e.g., console, file, HTTP). It is more feature-rich compared to @docusaurus/logger and is suitable for more complex logging requirements.

bunyan

Bunyan is a simple and fast JSON logging library for Node.js services. It provides a structured logging approach, which can be more powerful for analyzing logs compared to the simpler text-based logging of @docusaurus/logger.

pino

Pino is a low-overhead logging library for Node.js that focuses on performance. It is faster than many other logging libraries, including @docusaurus/logger, and is suitable for high-performance applications.

README

@docusaurus/logger

An encapsulated logger for semantically formatting console messages.

APIs

It exports a single object as default export: logger. logger has the following properties:

• Some useful colors.
  • red
  • yellow
  • green
  • bold
  • dim
• Formatters. These functions all have the signature (msg: unknown) => string. Note that their implementations are not guaranteed. You should only care about their semantics.
  • path: formats a file path.
  • url: formats a URL.
  • name: formats an identifier.
  • code: formats a code snippet.
  • subdue: subdues the text.
  • num: formats a number.
• The interpolate function. It is a template literal tag. The syntax can be found below.
• Logging functions. All logging functions can both be used as normal functions (similar to the console.log family, but only accepts one parameter) or template literal tags.
  • info: prints information.
  • warn: prints a warning that should be paid attention to.
  • error: prints an error (not necessarily halting the program) that signals significant problems.
  • success: prints a success message.
• The report function. It takes a ReportingSeverity value (ignore, log, warn, throw) and reports a message according to the severity.

A word on the error formatter

Beware that an error message, even when it doesn't hang the program, is likely going to cause confusion. When users inspect logs and find an [ERROR], even when the build succeeds, they will assume something is going wrong. Use it sparingly.

Docusaurus only uses logger.error when printing messages immediately before throwing an error, or when user has set the reporting severity of onBrokenLink, etc. to "error".

In addition, warn and error will color the entire message for better attention. If you are printing large blocks of help text about an error, better use logger.info.

Using the template literal tag

The template literal tag evaluates the template and expressions embedded. interpolate returns a new string, while other logging functions prints it. Below is a typical usage:

import logger from '@docusaurus/logger';

logger.info`Hello name=${name}! You have number=${money} dollars. Here are the ${
  items.length > 1 ? 'items' : 'item'
} on the shelf: ${items}
To buy anything, enter code=${'buy x'} where code=${'x'} is the item's name; to quit, press code=${'Ctrl + C'}.`;

An embedded expression is optionally preceded by a flag in the form [a-z]+= (a few lowercase letters, followed by an equals sign, directly preceding the embedded expression). If the expression is not preceded by any flag, it's printed out as-is. Otherwise, it's formatted with one of the formatters:

• path=: path
• url=: url
• name=: name
• code=: code
• subdue=: subdue
• number=: num

If the expression is an array, it's formatted by `\n- ${array.join('\n- ')}\n` (note it automatically gets a leading line end). Each member is formatted by itself and the bullet is not formatted. So you would see the above message printed as:

Changelog

3.6.2 (2024-11-19)

:bug: Bug Fix

• docusaurus-module-type-aliases
  • #10693 fix(types): add missing ambiant TS declarations for .md / .mdx partials (@slorber)
• docusaurus-theme-translations
  • #10688 fix(theme-translation): add and update Japanese translations (@Ryoga-exe)
• docusaurus
  • #10685 fix(cli): docusaurus --help should print plugin commands using extendCli() (@slorber)
• docusaurus-bundler
  • #10680 fix(bundler): allow CSS nesting by default, restore postcss-preset-env (@slorber)
• create-docusaurus
  • #10676 fix(create-docusaurus): add ts exclude to TS init template (@slorber)
• docusaurus-bundler, docusaurus-faster, docusaurus
  • #10648 fix(faster): Upgrade to Rspack 1.1.1, fix build progress bar display (@slorber)

:wrench: Maintenance

• #10691 chore(ci): retry yarn install to ignore temporary network errors (@slorber)

Committers: 5

• Junior_Gx (@goffxnca)
• Kyle Tsang (@kyletsang)
• Ryoga (@Ryoga-exe)
• Sébastien Lorber (@slorber)
• Zwyx (@Zwyx)