Consola

Elegant Console Logger for Node.js and Browser

Logging
unjs/consolaconsola

README

consola

Consola


Elegant Console Logger for Node.js and Browser

[![Standard JS][standard-js-src]][standard-js-href] [![npm version][npm-version-src]][npm-version-href] [![npm downloads][npm-downloads-src]][npm-downloads-href] [![package phobia][package-phobia-src]][package-phobia-href] [![bundle phobia][bundle-phobia-src]][bundle-phobia-href]

Why Consola?


👌  Easy to use
💅  Fancy output with fallback for minimal environments
🔌  Pluggable reporters
💻  Consistent command line interface (CLI) experience
🏷  Tag support
🚏  Redirect `console` and `stdout/stderr` to consola and easily restore redirect.
🌐  Browser support
⏯  Pause/Resume support
👻  Mocking support
👮‍♂️  Spam prevention by throttling logs

Installation


Using yarn:

  1. ``` sh
  2. yarn add consola
  3. ```

Using npm:

  1. ``` sh
  2. npm i consola
  3. ```

Getting Started


  1. ``` js
  2. const consola = require('consola')

  4. // See types section for all available types

  6. consola.success('Built!')
  7. consola.info('Reporter: Some info')
  8. consola.error(new Error('Foo'))
  9. ```

Will display in the terminal:

Screenshot 2020-01-28 at 14 15 15

NOTE: Alternatively, you can import consola from source. But don't forget to whitelist it for transpilation:

  1. ``` js
  2. import consola from 'consola/src/node'
  3. import consola from 'consola/src/browser'
  4. ```

Methods


#### `(logObject)` `(args...)`

Log to all reporters.

Example: consola.info('Message')

A list of available types can be found here.

addReporter(reporter)


- Aliases: add

Register a custom reporter instance.

removeReporter(reporter?)


- Aliases: remove, clear

Remove a registered reporter.

If no arguments are passed all reporters will be removed.

setReporters(reporter|reporter[])


Replace all reporters.

create(options)


Create a new Consola instance and inherit all parent options for defaults.

withDefaults(defaults)


Create a new Consola instance with provided defaults

withTag(tag)


- Aliases: withScope

Create a new Consola instance with that tag.

wrapConsole() restoreConsole()


Globally redirect all console.log, etc calls to consola handlers.

wrapStd() restoreStd()


Globally redirect all stdout/stderr outputs to consola.

wrapAll() restoreAll()


Wrap both, std and console.

console uses std in the underlying so calling wrapStd redirects console too.
Benefit of this function is that things like console.info will be correctly redirected to the corresponding type.

pauseLogs() resumeLogs()


- Aliases: pause/resume

Globally pause and resume logs.

Consola will enqueue all logs when paused and then sends them to the reported when resumed.

mockTypes


- Aliases: mock

Mock all types. Useful for using with tests.

The first argument passed to mockTypes should be a callback function accepting (typeName, type) and returning the mocked value:

  1. ``` js
  2. consola.mockTypes((typeName, type) => jest.fn())
  3. ```

Please note that with the example above, everything is mocked independently for each type. If you need one mocked fn create it outside:

  1. ``` js
  2. const fn = jest.fn()
  3. consola.mockTypes(() => fn)
  4. ```

If callback function returns a _falsy_ value, that type won't be mocked.

For example if you just need to mock consola.fatal:

  1. ``` js
  2. consola.mockTypes((typeName) => typeName === 'fatal' && jest.fn())
  3. ```

NOTE: Any instance of consola that inherits the mocked instance, will apply provided callback again.
This way, mocking works for withTag scoped loggers without need to extra efforts.

Fields


reporters


An array of active reporters.

level


The level to display logs. Any logs at or above this level will be displayed.
List of available levels here.

You can set the log level using the CONSOLA_LEVEL environment variable, which must have the numeric log level as its value.

logObject


The logObject is a free-to-extend object which will be passed to reporters.

Standard fields:

- message
- additional
- args
- date
- tag

Extra fields:

- badge

Reporters


Choose between one of the built-in reporters or bring in your own one.

By default FancyReporter is registered for modern terminals or BasicReporter will be used if running in limited environments such as CIs.

Available reporters:

- BasicReporter
- FancyReporter
- JSONReporter
- WinstonReporter

Creating your own reporter


A reporter (class or object) exposes log(logObj) method.
To get more info about how to write your own reporter, take a look into the linked implementations above.

Types


Types are used to actually log messages to the reporters.
Each type is attached to a _logging level_.

A list of all available default types is here.

Creating a new instance


Consola has a global instance and is recommended to use everywhere.
In case more control is needed, create a new instance.

  1. ``` js
  2. import consola from 'consola'

  4. const logger = consola.create({
  5.     // level: 4,
  6.     reporters: [
  7.       new consola.JSONReporter()
  8.     ],
  9.     defaults: {
  10.       additionalColor: 'white'
  11.     }
  12. })
  13. ```

Integrations


With jest


  1. ``` js
  2. describe('your-consola-mock-test', () => {
  3.   beforeAll(() => {
  4.     // Redirect std and console to consola too
  5.     // Calling this once is sufficient
  6.     consola.wrapAll()
  7.   })

  9.   beforeEach(() => {
  10.     // Re-mock consola before each test call to remove
  11.     // calls from before
  12.     consola.mockTypes(() => jest.fn())
  13.   })


  16.   test('your test', async () => {
  17.     // Some code here

  19.     // Let's retrieve all messages of `consola.log`
  20.     // Get the mock and map all calls to their first argument
  21.     const consolaMessages = consola.log.mock.calls.map(c => c[0])
  22.     expect(consolaMessages).toContain('your message')
  23.   })

  25. })
  26. ```

With jsdom


  1. ``` js
  2. {
  3.   virtualConsole: new jsdom.VirtualConsole().sendTo(consola)
  4. }
  5. ```

License


MIT - Made with 💖 By Nuxt.js team!


[standard-js-src]: https://flat.badgen.net/badge/code%20style/standard/green
[standard-js-href]: https://standardjs.com

[npm-version-src]: https://flat.badgen.net/npm/v/consola/latest
[npm-version-href]: https://npmjs.com/package/consola

[npm-downloads-src]: https://flat.badgen.net/npm/dt/consola
[npm-downloads-href]: https://npmjs.com/package/consola

[package-phobia-src]: https://flat.badgen.net/packagephobia/install/consola
[package-phobia-href]: https://packagephobia.now.sh/result?p=consola

[bundle-phobia-src]: https://flat.badgen.net/bundlephobia/minzip/consola
[bundle-phobia-href]: https://bundlephobia.com/result?p=consola