📦 logger

An encapsulated logger for semantically formatting console messages.

Authors of packages in the Docusaurus ecosystem are encouraged to use this package to provide unified log formats.

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.

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: