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.
• Pretty logs - Crowlog pretty log command to display logs in a more readable format for development.

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');

Methods

Crowlog logger provides 4 different logging methods: debug, info, warn, and error.

logger.debug(/* ... */);
logger.info(/* ... */);
logger.warn(/* ... */);
logger.error(/* ... */);

Child logger and factory

Crowlog logger provides a createChildLogger method to create a child logger that inherit the configuration of the parent logger.

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

const logger = createLogger({ namespace: 'my-app' });
const childLogger = logger.createChildLogger({ namespace: 'child' });

Alternatively, you can use the createLoggerFactory to create a logger factory that can be used to create child loggers with the same configuration.

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

const createLogger = createLoggerFactory({ transports: /* ... */, plugins: /* ... */ });
const logger = createLogger({ namespace: 'child' });

Transports

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

Stdout transport

The stdout transport writes the logs to the standard output stream. It's the default transport.

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

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

logger.info('Hello world');

By default, the stdout transport serializes the log args to a JSON string and use the console.log function to write the logs to the standard output stream for cross-compatibility with most environments.

You can customize the serialization and the write function by providing a custom serialize and write function to the transport.

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

const logger = createLogger({
  namespace: 'my-app',
  transports: [
    createStdoutLoggerTransport({
      serialize: ({ level, message, timestampMs, namespace, data }) => `[${level}] ${message}`,
      // default : (args) => JSON.stringify(args),
      writeToStdout: (serializedLog) => process.stdout.write(serializedLog),
      // default : (serializedLog) => console.log(serializedLog),
    })
  ]
});

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

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.

Global log context plugin

The global log context plugin allows you to set global context data that will be automatically included in all logs. This is useful for adding application-wide context like environment, version, or any other static data that should appear in every log entry.

Unlike the async context plugin, the global context is shared across all loggers using the same plugin instance and persists until explicitly changed.

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

const { globalContextPlugin, setGlobalLogContext, addToGlobalLogContext, getGlobalLogContext } = createGlobalLogContextPlugin();

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

// Set the global context
setGlobalLogContext({ environment: 'production', version: '1.0.0' });

logger.info('Application started');
// Output includes: { environment: 'production', version: '1.0.0' }

// Add to the existing global context
addToGlobalLogContext({ region: 'us-east-1' });

logger.info('Processing request');
// Output includes: { environment: 'production', version: '1.0.0', region: 'us-east-1' }

API:

• setGlobalLogContext(context) - Replace the entire global context
• addToGlobalLogContext(context) - Shallow merge new properties into the existing global context
• getGlobalLogContext() - Retrieve the current global context

TypeScript support:

You can provide a type for the global context to ensure type safety when setting or adding to the global context.

type MyGlobalContext = {
  environment: string;
  version: string;
  region?: string;
};

const { globalContextPlugin, setGlobalLogContext } = createGlobalLogContextPlugin<MyGlobalContext>();

// TypeScript will enforce the shape of the context
setGlobalLogContext({ environment: 'production', version: '1.0.0' });

[!NOTE] When there's a conflict between global context and log-specific data, the log-specific data takes precedence.

Pretty logs

Crowlog provides a pretty log command to display logs in a more readable format for development.

# using node
node index.js | npx crowlog-pretty

# using tsx
tsx watch index.ts | npx crowlog-pretty

See the pretty README for more details.

Noop Logger

The @crowlog/logger package also provides a createNoopLogger function to create a logger that does nothing. This is useful for testing or when you want to disable logging.

// Some function with an inected logger
function doSomething({ logger }) {
  logger.info('Will do something');
  const foo = 42;
  logger.debug({ foo }, 'Did something');

  return foo;
}

// In test for example
import { createNoopLogger } from '@crowlog/logger';

const logger = createNoopLogger();

describe("doSomething", () => {
  test("stuff happens", () => {
    // no logs will be printed
    const result = doSomething({ logger = createNoopLogger() });

    expect(result).toBe(42);
  })
})

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.

The icon is the Logs icon from the Tabler collection