Loxer

Loxer is a middleware logger that allows you to:

• distribute logs to different output streams (dev / prod / log / error)
• write logs at a level (error / warn / info / debug)
• categorize logs in modules (each logging up to its own threshold)
• connect logs to each other to "boxes"
• improve error logs (with more information)
• get significantly better visualization of the logs
• visualize the data flow (including time measurement)
• full Typescript support
• rich output of values (props) for debugging purposes

With Loxer, logs never have to be deleted again, as they hardly use any resources when switched off. Logs and error records can easily be forwarded to crash reporting systems such as Firebase. This makes it possible to get error reports that are just as good in the production environment as in the development environment. Furthermore, errors in concurrent functional processes can be detected more easily.

Documentation

The API Reference provides a complete overview of all the features of the package. Furthermore, the complete source code is documented with js-doc and typed with typscript, which guarantees full IDE support.

The Documentation contains detailed instructions on how to use the package.

The Performance Tests documents how small the influence of the package is on the performance of an application.

Usage

Write logs in an intuitive way:

// initialize it somewhere (once) -> singleton
Loxer.init();

// simple log
Loxer.log('my message');

// highlight logs
Loxer.highlight().log('my message');

// use different levels
Loxer.error('that is serious');
Loxer.warn('still working, but something is wrong');
Loxer.info('an alias for .log(...)');
Loxer.debug('just informative');

// set modules
Loxer.module('AUTH').log('user logged in');

// use boxes
const lox = Loxer.open('opening log');
Loxer.of(lox).add('appended log');
Loxer.of(lox).error('appended error');
Loxer.of(lox).close('closing log');

// combine everything like you want
Loxer.module('AUTH').highlight().debug('highlighted debug log for module Authentication');

// use shortcuts for the methods - every level opens a box too
const lox2 = Loxer.h().m('AUTH').debug.open('highlighted debug box for module Authentication');
Copy

For a complete guide on how to use everything, definitely take a look at the Documentation

Plain-function tracing

Loxer can open and close a trace box automatically around a named plain function during the build. This requires Loxer 3, Babel 8, and Node 22.18 or newer for the tracing plugin.

pnpm add loxer
pnpm add -D @babel/core @babel/preset-typescript babel-plugin-loxer-trace
Copy

Register the plugin in the Babel configuration that transforms the marked TypeScript files:

// babel.config.mjs
export default {
  presets: ['@babel/preset-typescript'],
  plugins: ['babel-plugin-loxer-trace'],
};
Copy

Initialize Loxer with every module that a trace or log uses, then import trace from loxer/trace and put its marker immediately after the named function binding:

import { Loxer } from 'loxer';
import { trace } from 'loxer/trace';

Loxer.init({
  modules: {
    ORDER: { color: '#00ff99', fullName: 'Order', devLevel: 'info', prodLevel: 'error' },
  },
});

function submitOrder(orderId: string) {
  Loxer.m('ORDER').log(`Submitting ${orderId}`);
  return orderId;
}

trace(submitOrder, { moduleId: 'ORDER', openMessage: 'args' });
Copy

To trace several functions the same way, pass an array literal of them and the options they share:

trace([submitOrder, cancelOrder], { moduleId: 'ORDER', openMessage: 'args' });
Copy

trace() is a build-time marker, not a runtime wrapper. Every module that executes a marker must pass through the Babel plugin; otherwise the marker throws to signal a missing build configuration.

For Vite, add the adapter and register it as a normal Vite plugin:

pnpm add -D vite-plugin-loxer-trace
Copy

// vite.config.ts
import { defineConfig } from 'vite';
import loxerTrace from 'vite-plugin-loxer-trace';

export default defineConfig({
  plugins: [loxerTrace()],
});
Copy

See the plain-function tracing guide and the Babel plugin README for supported function shapes, options, and transform details.

Preview Example

Consider the following log output (without the log date):

As you can see the logs might tell something considering you know where they come from and what they do, but obviously they seem to be pretty uninformative.

Let's see what Loxer can do about this:

The log messages are exactly the same, but with a litte configuration you can see what is happening in the application. Even if you are not familiar with the code you can follow the implemented data flow by just one sight.

Watch this comparison with a slider

Installation

npm i --save loxer, pnpm add loxer, or yarn add loxer thats it.

Deps

none - Loxer ships with zero runtime dependencies.