Repository files navigation

Elegant Console Wrapper

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

Using npm:

npm i consola

Using yarn:

yarn add consola

Using pnpm:

pnpm i consola

// ESMimport{consola,createConsola}from"consola";// CommonJSconst{ consola, createConsola}=require("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(newError("This is an example error. Everything is fine!"));consola.box("I am a simple box");awaitconsola.prompt("Deploy to the production?",{type:"confirm",});

Will display in the terminal:

You can use smaller core builds without fancy reporter to save 80% of the bundle size:

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

Log to all reporters.

Example:consola.info('Message')

Show an input prompt. Type can either oftext,confirm,select ormultiselect.

If prompt is canceled by user (with Ctrol+C), default value will be resolved by default. This strategy can be configured by setting{ cancel: "..." } option:

• "default" - Resolve the promise with thedefault value orinitial value.
• "undefined" - Resolve the promise withundefined.
• "null" - Resolve the promise withnull.
• "symbol" - Resolve the promise with a symbolSymbol.for("cancel").
• "reject" - Reject the promise with an error.

Seeexamples/prompt.ts for usage examples.

• Aliases:add

Register a custom reporter instance.

• Aliases:remove,clear

Remove a registered reporter.

If no arguments are passed all reporters will be removed.

Replace all reporters.

Create a newConsola instance and inherit all parent options for defaults.

Create a newConsola instance with provided defaults

• Aliases:withScope

Create a newConsola instance with that tag.

Globally redirect allconsole.log, etc calls to consola handlers.

Globally redirect all stdout/stderr outputs to consola.

Wrap both, std and console.

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

• Aliases:pause/resume

Globally pause and resume logs.

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

• Aliases:mock

Mock all types. Useful for using with tests.

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

// Jestconsola.mockTypes((typeName,type)=>jest.fn());// Vitestconsola.mockTypes((typeName,type)=>vi.fn());

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

// Jestconstfn=jest.fn();// Vitestconstfn=vi.fn();consola.mockTypes(()=>fn);

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

For example if you just need to mockconsola.fatal:

// Jestconsola.mockTypes((typeName)=>typeName==="fatal"&&jest.fn());// Vitestconsola.mockTypes((typeName)=>typeName==="fatal"&&vi.fn());

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

Consola ships with 3 built-in reporters out of the box. A fancy colored reporter by default and fallsback to a basic reporter if running in a testing or CI environment detected usingunjs/std-env and a basic browser reporter.

You can create a new reporter object that implements{ log(logObject): () => { } } interface.

Example: Simple JSON reporter

import{createConsola}from"consola";constconsola=createConsola({reporters:[{log:(logObj)=>{console.log(JSON.stringify(logObj));},},],});// Prints {"date":"2023-04-18T12:43:38.693Z","args":["foo bar"],"type":"log","level":2,"tag":""}consola.log("foo bar");

Example: Exit on fatal errors

import{consola}from'consola';consola.addReporter({log(logObj){if(logObj.type==='fatal'){process.exit(1)}}})// Will exit on this line.consola.fatal("fatal error");

Consola only shows logs with configured log level or below. (Default is3)

Available log levels:

• 0: Fatal and Error
• 1: Warnings
• 2: Normal logs
• 3: Informational logs, success, fail, ready, start, ...
• 4: Debug logs
• 5: Trace logs
• -999: Silent
• +999: Verbose logs

You can set the log level by either:

• Passinglevel option tocreateConsola
• Settingconsola.level on instance
• Using theCONSOLA_LEVEL environment variable (not supported for browser and core builds).

Log types are exposed asconsola.[type](...) and each is a preset of styles and log level.

A list of all available built-in types isavailable here.

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

import{createConsola}from"consola";constlogger=createConsola({// level: 4,// fancy: true | false// formatOptions: {//     columns: 80,//     colors: false,//     compact: false,//     date: false,// },});

describe("your-consola-mock-test",()=>{beforeAll(()=>{// Redirect std and console to consola too// Calling this once is sufficientconsola.wrapAll();});beforeEach(()=>{// Re-mock consola before each test call to remove// calls from before// Jestconsola.mockTypes(()=>jest.fn());// Vitestconsola.mockTypes(()=>vi.fn());});test("your test",async()=>{// Some code here// Let's retrieve all messages of `consola.log`// Get the mock and map all calls to their first argumentconstconsolaMessages=consola.log.mock.calls.map((c)=>c[0]);expect(consolaMessages).toContain("your message");});});

{newjsdom.VirtualConsole().sendTo(consola);}

// ESMimport{stripAnsi,centerAlign,rightAlign,leftAlign,align,box,colors,getColor,colorize,}from"consola/utils";// CommonJSconst{ stripAnsi}=require("consola/utils");

Objects sent to the reporter could lead to unexpected output when object is close to internal object structure containing eithermessage orargs props. To enforce the object to be interpreted as pure object, you can use theraw method chained to any log type.

Example:

// Prints "hello"consola.log({message:"hello"});// Prints "{ message: 'hello' }"consola.log.raw({message:"hello"});

MIT