Crowlog - Extendable JS logging library

Crowlog is a simple, lightweight, zero-dependency, and extendable logging library that is designed to be used in any project.

Features

• Ultra lightweight - Crowlog is very lightweight (less than 1kB minified + gzipped, see comparison).
• Zero dependencies - No runtime dependencies, just pure JavaScript.
• Extendable - Crowlog is designed to be extendable, so you can add your own transports and plugins to it.
• Simple - Crowlog is designed to be simple and easy to use.
• Fully typed - Crowlog is fully typed, so you can get autocomplete and type safety when using it.
• Any environment - Crowlog works in any environment, including Node.js, browsers, and the edge.
• Testing friendly - Crowlog is designed to be testing friendly, so you can easily test your logs with the in-memory transport.
• Slightly opinionated - Crowlog is designed to be slightly opinionated, so it has a default transport and some plugins.

Installation

# pnpm 
pnpm install @crowlog/logger

# npm
npm install @crowlog/logger

# yarn
yarn add @crowlog/logger

Usage

Basic usage:

import { createLogger } from '@crowlog/logger';

const logger = createLogger({ namespace: 'my-app' });

logger.info('Hello world');
logger.error({ error: new Error('...') }, 'Something went wrong');

[!NOTE] The logging interface is either a single string message or a data object and a message string tuple.

logger.info('Hello world');
logger.info({ foo: 'bar' }, 'Hello world');

Transports

A transport specifies where the logs are sent to. By default, Crowlog uses the console transport.

Console transport

The console transport use the standard console to log the messages to stdout.

import { createLogger, createConsoleLoggerTransport } from '@crowlog/logger';

const logger = createLogger({ namespace: 'my-app' });
// equivalent to
const logger = createLogger({ namespace: 'my-app', transports: [createConsoleLoggerTransport()] });

logger.info('Hello world');

In-memory transport

The in-memory transport is a transport that stores the logs in memory. It is useful for testing and for debugging.

It provides a getLogs method to retrieve the logs.

import { createLogger, createInMemoryLoggerTransport } from '@crowlog/logger';

const inMemoryTransport = createInMemoryLoggerTransport();

const logger = createLogger({ namespace: 'my-app', transports: [inMemoryTransport] });

logger.info('Hello world');
logger.error({ foo: 'bar' }, 'Something went wrong');

// get the logs
const logs = inMemoryTransport.getLogs();
/*
[
  {
    level: 'info',
    message: 'Hello world',
    timestamp: 1738878633123,
    namespace: 'my-app',
    data: {},
  },
  {
    level: 'error',
    message: 'Something went wrong',
    timestamp: 1738878633123,
    namespace: 'my-app',
    data: { foo: 'bar' },
  },
]

[!TIP] The getLogs method accepts a excludeTimestampMs option to exclude the timestamp from the logs for better DX in writing more deterministic tests.

const logs = inMemoryTransport.getLogs({ excludeTimestampMs: true });

Plugins

A plugin permit to extend the logger with custom functionality.

Async context plugin

The async context plugin is a plugin that adds the async context to the logs.

Async context plugin

Permit to easily add context data to the logs, it's useful in http servers to add log context that follow the lifecycle of a request (like a request id).

[!IMPORTANT] This plugin is only available environment that supports async_hooks like Node.js or cloudflare workers with compatibility flags.

Install the plugin:

# pnpm
pnpm install @crowlog/async-context-plugin

# npm
npm install @crowlog/async-context-plugin

# yarn
yarn add @crowlog/async-context-plugin

Use the plugin:

import { createLogger } from '@crowlog/logger';
import { createAsyncContextPlugin, addLogContext, wrapWithLoggerContext } from '@crowlog/async-context-plugin';

const logger = createLogger({ namespace: 'my-app', plugins: [createAsyncContextPlugin()] });

// create a context, some initial context data can be added
wrapWithLoggerContext({ requestId: '123' }, () => {
  addLogContext({ userId: '123' });

  // logs within the context will have the requestId and userId
  logger.info('Hello world');
});

More details about the async context plugin can be found in the async-context-plugin README.

Comparison

License

This project is licensed under the MIT License. See the LICENSE file for more information.

Credits

This project is crafted with ❤️ by Corentin Thomasset. If you find this project helpful, please consider supporting my work.