# @haensl/iso-log

> Isomorphic logger with Bunyan and Sentry support.

Latest version **3.1.2** (published 2026-05-23) · MIT license · 0 weekly downloads

## Install

```sh
npm install @haensl/iso-log
pnpm add @haensl/iso-log
yarn add @haensl/iso-log
bun add @haensl/iso-log
```

## Health

**Score 50/100 (C)** — status: active.

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types.

## Facts

| | |
|---|---|
| Version | 3.1.2 |
| Published | 2026-05-23 |
| First published | 2023-06-13 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 9.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | HP Dietz |
| Maintainers | haensl |
| Keywords | isomorphic, log, bunyan, sentry, console |

## Links

- npm: https://www.npmjs.com/package/@haensl/iso-log
- Repository: https://github.com/haensl/iso-log
- Homepage: https://github.com/haensl/iso-log#readme
- Issues: https://github.com/haensl/iso-log/issues
- Funding: https://github.com/sponsors/haensl
- npm.io page: https://npm.io/package/@haensl/iso-log

## Dependencies (1)

- [@haensl/log](https://npm.io/package/@haensl/log.md) ^1.3.11

## Alternatives

- [cli-color](https://npm.io/package/cli-color.md) — 3.4M weekly downloads
- [log](https://npm.io/package/log.md) — 1.3M weekly downloads
- [logstash-client](https://npm.io/package/logstash-client.md) — 4.5K weekly downloads
- [@nocobase/plugin-logger](https://npm.io/package/@nocobase/plugin-logger.md) — 2.0K weekly downloads
- [child-process-debug](https://npm.io/package/child-process-debug.md) — 695 weekly downloads

## Recent versions

- 3.1.2 (latest) — 2026-05-23
- 3.1.1 — 2026-05-23
- 3.1.0 — 2026-05-23
- 3.0.1 — 2026-05-23
- 3.0.0 — 2026-05-23
- 2.0.7 — 2024-11-05
- 2.0.6 — 2024-11-05
- 2.0.5 — 2024-05-24
- 2.0.4 — 2024-03-12
- 2.0.3 — 2023-09-26
- 2.0.2 — 2023-07-03
- 2.0.1 — 2023-06-15
- 2.0.0 — 2023-06-14
- 1.0.1 — 2023-06-13
- 1.0.0 — 2023-06-13

## README

# @haensl/iso-log

A tiny isomorphic logging facade for JavaScript applications.

[![NPM](https://nodei.co/npm/@haensl%2Fiso-log.png?downloads=true)](https://nodei.co/npm/@haensl%2Fiso-log/)
[![npm version](https://badge.fury.io/js/@haensl%2Fiso-log.svg)](http://badge.fury.io/js/@haensl%2Fiso-log)
[![CircleCI](https://circleci.com/gh/haensl/iso-log.svg?style=svg)](https://circleci.com/gh/haensl/iso-log)


`@haensl/iso-log` provides a single logging API that works in browsers, Node.js, and frameworks such as Next.js without introducing runtime dependencies on server-only modules.

The logger starts in a buffering mode and can be initialized later once the host application knows which logger and error reporting implementation it wants to use.

## Features

- Isomorphic (Browser + Node.js)
- No hard dependency on Bunyan, Sentry, or any other logging backend
- Buffers log messages before initialization
- Optional error reporting integration
- Tiny API surface
- ESM-first

## Installation

```bash
npm install @haensl/iso-log
```

## Quick Start

```js
import log from '@haensl/iso-log';

log.info('Application starting...');

log.init();

log.info('Application started.');
```

## Initialization

The logger can be initialized with:

- a custom logger implementation
- an error reporting callback

```js
import log from '@haensl/iso-log';

log.init({
  logger: console,
  onError: (error) => {
    console.error('Reporting error:', error);
  }
});
```

### Configuration

| Option | Type | Required | Description |
|----------|----------|----------|----------|
| `logger` | Object | No | Logger implementation to use |
| `onError` | Function | No | Called for every `Error` passed to `warn()` or `error()` |

## Logger Interface

A custom logger should implement any subset of:

```js
{
  debug(...args) {},
  info(...args) {},
  warn(...args) {},
  error(...args) {}
}
```

Methods are optional.

Example:

```js
log.init({
  logger: {
    info: (...args) => console.log('[INFO]', ...args),
    error: (...args) => console.error('[ERROR]', ...args)
  }
});
```

## Error Reporting

Errors passed to `warn()` and `error()` can be forwarded to an external service.

```js
log.init({
  onError: (error) => {
    sentry.captureException(error);
  }
});
```

Example:

```js
log.error(new Error('Something exploded'));
```

The supplied callback receives:

```js
Error
```

instances only.

Non-error arguments are ignored.

```js
log.error(
  'Something exploded',
  new Error('Boom')
);
```

Only the `Error` object is reported.

## Buffering

Calls made before initialization are buffered.

```js
log.info('A');
log.info('B');
log.info('C');

log.init({
  logger: console
});
```

The buffered messages are flushed in FIFO order:

```text
A
B
C
```

This makes it safe to log during application startup before logging infrastructure has been configured.

## API

### `log.init(options?)`

Initialize the logger.

```js
log.init({
  logger,
  onError
});
```

### `log.debug(...args)`

Write a debug message.

```js
log.debug('Loading user', userId);
```

### `log.info(...args)`

Write an informational message.

```js
log.info('Server started');
```

### `log.warn(...args)`

Write a warning.

Errors are forwarded to `onError`.

```js
log.warn(
  'Unexpected response',
  new Error('Invalid payload')
);
```

### `log.error(...args)`

Write an error.

Errors are forwarded to `onError`.

```js
log.error(
  'Request failed',
  new Error('Connection refused')
);
```

## Bunyan Example

```js
import bunyan from 'bunyan';
import log from '@haensl/iso-log';

log.init({
  logger: bunyan.createLogger({
    name: 'api'
  })
});
```

## Sentry Example

```js
import * as Sentry from '@sentry/node';
import log from '@haensl/iso-log';

Sentry.init({
  dsn: process.env.SENTRY_DSN
});

log.init({
  logger: console,
  onError: Sentry.captureException
});
```

## Next.js Example

Client:

```js
import * as Sentry from '@sentry/nextjs';
import log from '@haensl/iso-log';

log.init({
  onError: Sentry.captureException
});
```

Server:

```js
import bunyan from 'bunyan';
import * as Sentry from '@sentry/nextjs';
import log from '@haensl/iso-log';

log.init({
  logger: bunyan.createLogger({
    name: 'web'
  }),
  onError: Sentry.captureException
});
```

## [Changelog](CHANGELOG.md)

## [License](LICENSE)

---
_Source: https://npm.io/package/@haensl/iso-log · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._