space-logger

Colourful, configurable logger for Node.js/TypeScript console output (via leeks.js or chalk), file logging with daily rotation and automatic cleanup, a dedicated error log file, webhook/Discord/Slack notifications, performance timers, custom log levels and namespaces.

Features

• 🎨 Coloured console output (Minecraft style & colour codes via leeks.js, or chalk)
• 📁 File logging with daily rotation and automatic cleanup of old logs
• 🚨 Separate error log file out of the box
• 🔔 Webhook / Discord / Slack transports for critical alerts
• 🏷️ Custom log levels and namespaces (logger.info.database('...'))
• ⏱️ Built-in performance timers (logger.time() / logger.timeEnd())
• 👶 Child loggers that inherit and override parent configuration
• 🧩 Fully typed (TypeScript), ships with its own .d.ts files

Installation

npm install space-logger

Quick start

const { logger } = require('space-logger');

logger.info('Server started on port %d', 3000);
logger.warn('Cache is almost full');
logger.error('Something went wrong', new Error('oops'));

logger is a ready to use default instance. If you need your own configuration, use createLogger(options) instead:

const { createLogger, transports } = require('space-logger');

const logger = createLogger({
	levels: {
		debug: 'debug',
		info: 'info',
		warn: 'warn',
		error: 'error',
	},
	namespaces: ['database', 'commands'],
	transports: [
		new transports.ConsoleTransport(),
		new transports.FileTransport(),
	],
});

TypeScript

import { createLogger, transports, LoggerOptions } from 'space-logger';

const options: Partial<LoggerOptions> = {
	namespaces: ['http'],
};

const logger = createLogger(options);

Log levels

By default the following levels are configured (name → console method used):

| Level | Console method | |--------------|----------------| | debug | console.debug | | verbose | console.debug | | info | console.info | | success | console.info | | warn | console.warn | | notice | console.warn | | error | console.error | | critical | console.error |

Levels also define severity order a transport with level: 'warn' will receive warn, notice, error and critical logs, but not debug/info. You can fully replace the level list with your own:

const logger = createLogger({
	levels: {
		debug: 'debug',
		info: 'info',
		warn: 'warn',
		error: 'error',
		fatal: 'error',
	},
});

logger.fatal('Unrecoverable error');

Namespaces

Namespaces let you tag logs coming from a specific part of your app (e.g. a database module) while still using the normal log level methods:

const logger = createLogger({
	namespaces: ['database', 'commands'],
});

logger.info('App started');           // no namespace
logger.info.database('Connected');    // (DATABASE) Connected
logger.error.commands('Failed to run /ping');

Performance timers

logger.time('db-query');
await db.query('SELECT 1');
logger.timeEnd('db-query'); // logs "db-query: 12.345ms" at debug level (or your chosen level)

Child loggers

Create a logger that inherits the parent's configuration but overrides part of it (e.g. a different set of transports for a submodule):

const base = createLogger({ transports: [new transports.ConsoleTransport()] });
const dbLogger = base.child({ namespaces: ['query'] });

Transports

Every transport has its own independent minimum level a log is written to a transport only if its level is severe enough for that transport.

ConsoleTransport

Prints logs to stdout/stderr.

new transports.ConsoleTransport({
	formatter: 'leeks',       // 'leeks' (default, Minecraft-style '&' colour codes) or 'chalk'
	level: 'info',
	timestamp: 'DD/MM/YY HH:mm:ss',
	colours: {
		info: '&3',
		error: '&4',
		// ...one entry per level
	},
});

| Option | Type | Default | Description | |-------------|-----------------------------------------|------------------------------|--------------| | formatter | 'leeks' \| 'chalk' | 'leeks' | Colour engine used for output. | | colours | { [level]: string } | leeks.js colour codes | Per-level colour/style. When formatter: 'chalk' and no colours given, a matching chalk palette is used automatically. | | format | string \| (log) => string | built-in formatter | Custom line format. String templates support {level}, {LEVEL}, {namespace}, {NAMESPACE}, {file}, {line}, {column}, {content}, {timestamp}. | | level | string | 'info' | Minimum level this transport writes. | | timestamp | string \| (date) => string | 'DD/MM/YY HH:mm:ss' | Timestamp format (via @eartharoid/dtf) or a custom function. |

FileTransport

Writes logs to disk with daily rotation and automatic cleanup of old files.

new transports.FileTransport({
	directory: './logs',
	file: 'YYYY-MM-DD.log',
	level: 'info',
	clean_directory: 7, // delete .log files older than 7 days, -1 disables cleanup
	new_file: 'day',     // 'day' (rotate daily) or 'run' (one file per process run)
});

| Option | Type | Default | Description | |-------------------|----------------------------------------------|-----------------------|--------------| | directory | string | './logs' | Folder logs are written to (created automatically). | | file | string \| () => string | 'YYYY-MM-DD.log' | File name (date-formatted) or a function returning one. | | clean_directory | number | 7 | Days to keep old .log files before deleting them. -1 disables cleanup. | | new_file | 'day' \| 'run' | 'day' | Whether to start a new file every day or keep one file for the process lifetime. | | header | string \| () => string | built-in banner | Text written at the top of a new file. | | format | string \| (log) => string | built-in formatter | Same placeholders as ConsoleTransport.format. | | level | string | 'info' | Minimum level this transport writes. | | name | string | 'A logger-pro project' | Used in the default file header. | | timestamp | string \| (date) => string | 'DD/MM/YY HH:mm:ss' | Timestamp format or custom function. |

ErrorFileTransport

A FileTransport preconfigured to only write error/critical logs to a separate folder.

new transports.ErrorFileTransport(); // -> ./logs/errors/error-YYYY-MM-DD.log

Accepts all the same options as FileTransport.

WebhookTransport

Sends logs as an HTTP POST request to any URL. Requires Node.js 18+ (uses the global fetch).

new transports.WebhookTransport({
	url: process.env.MY_WEBHOOK_URL,
	level: 'error',
	method: 'POST',
	timeout: 5000,
	retry: 1,
	format: (log) => ({ text: `${log.level.name}: ${log.content}` }),
});

DiscordTransport

Sends logs as Discord embeds via a webhook. Extends WebhookTransport.

new transports.DiscordTransport({
	url: process.env.DISCORD_WEBHOOK_URL,
	username: 'My Bot Logger',
	level: 'error', // default: only error/critical
});

SlackTransport

Sends logs as Slack attachments via a webhook. Extends WebhookTransport.

new transports.SlackTransport({
	url: process.env.SLACK_WEBHOOK_URL,
	channel: '#alerts',
	level: 'error', // default: only error/critical
});

Custom transports

Extend the abstract Transport class and implement write(log):

import { Transport, Log } from 'space-logger';

class DatabaseTransport extends Transport {
	write(log: Log): void {
		// persist `log` however you like
	}
}

Examples

The examples/ folder has a standalone, runnable script for every feature of the logger - default usage, custom levels and namespaces, every transport (Console, File, ErrorFile, Webhook, Discord, Slack), performance timers, child loggers and writing your own transport. See examples/README.md for the full list and how to run them.

API reference

createLogger(options?): Logger

Creates a new, independently configured Logger instance.

logger

Default, ready-to-use Logger singleton (import { logger } from 'space-logger').

Logger

• logger[level](...args) — log at the given level (util.format style, e.g. logger.info('value: %d', 42)).
• logger[level][namespace](...args) — log at the given level under a namespace.
• logger.time(label?) / logger.timeEnd(label?, level?, ...args) — performance timers.
• logger.child(overrides?) — create a child logger with merged configuration.
• logger.options — get/set the current configuration (setter re-applies init()).

LoggerOptions

interface LoggerOptions {
	levels: { [name: string]: string };  // name -> console method ('debug' | 'info' | 'warn' | 'error')
	namespaces: string[];
	transports: Transport[];
}

Building from source

git clone https://github.com/kicpeross/space-logger.git
cd space-logger
npm install
npm run build   # compiles src/ (TypeScript) -> dist/ (CommonJS + .d.ts)

License

MIT © Kicpeross