JavaScript

The justlog3 npm package writes log lines to a file and, once you set an API token, sends them to JustLog3 Cloud.

Install

npm install justlog3

Node.js 18 or newer. The package supports ESM and CommonJS and includes TypeScript types. Source: github.com/OAzizjon/justlog3. License: MIT.

Import the API with ESM:

import { Logger, BasicLogger, setApiToken, shutdown } from 'justlog3'

Or CommonJS:

const { Logger, BasicLogger, setApiToken, shutdown } = require('justlog3')

Log to a file

import { Logger } from 'justlog3'

const logger = new Logger('app.log')

logger.log('Hi...')
logger.log('debug', { offConsole: true })
logger.log('There is some error!', { red: true })
logger.log('OK', { green: true })
logger.log('There is a critical error!', { red: true, customPrefix: 'CRITICAL!!' })

.log is added to the filename if it is missing. The console shows colored lines; app.log gets one line per call with a prefix and a local timestamp with milliseconds:

GREY:2026-10-05 14:03:12.517 - Hi...

With withTime: false, lines have no timestamp:

GREY: Hi...

An Error passed to log() is written with its stack trace. Other objects are formatted on one line with util.inspect.

Send to JustLog3 Cloud

import { Logger, setApiToken } from 'justlog3'

setApiToken(process.env.JUSTLOG3_TOKEN, { url: 'https://jl3-cloud.site/api/logs/' })
const logger = new Logger('app.log')
logger.log('This line goes to the file and to the cloud')

Call setApiToken() once, before or after creating loggers. Keep the token in an environment variable rather than in code.

• Lines are sent every 5 seconds, or sooner once 75 lines are waiting.
• A request carries at most 5,000 lines and 512 KB of text; bodies from 1 KB are gzip-compressed.
• Each logger keeps up to 10,000 unsent lines; beyond that the oldest are dropped with a single warning.
• No answer or HTTP 5xx: the batch is resent with the same sequence number. The wait starts at 5 s and doubles up to 5 minutes.
• HTTP 429: nothing is sent until Retry-After; lines stay buffered.
• HTTP 401 / 403: cloud sending stops, files keep being written. Call setApiToken() again with a valid token.
• HTTP 413: later batches carry fewer lines.

Cloud options: url, flushIntervalMs (default 5,000), timeoutMs (default 5,000), and maxBatchLines (default 5,000).

Levels

import { BasicLogger } from 'justlog3'

const logger = new BasicLogger('app.log', { consoleLevel: 'INFO' })
logger.debug('cache warmed')
logger.info('server started')
logger.success('processed items')
logger.warning('disk 85% full')
logger.error('payment failed')
logger.critical('database is down')

BasicLogger has debug, info, success, warning, error, and critical methods. consoleLevel only filters the console. Every line still goes to the file and the cloud.

Shutdown

• On a normal exit, a beforeExit hook flushes files and sends what is left, bounded by timeoutMs.
• No signal handlers are installed. In containers, add a handler to flush before exiting:

import { shutdown } from 'justlog3'

process.on('SIGTERM', async () => {
  await shutdown()
  process.exit(0)
})

process.exit() skips beforeExit, so call await shutdown() before it. Use file: false for serverless environments.

Logger options

new Logger('app.log', {
  withTime: true,
  filemode: 'a',
  cycles: 50,
  cloudCycles: 75,
  file: true,
})

Use .flush() to flush a logger's buffered lines. Loggers also provide .status(). If a disk write fails (disk full, file locked), the error and the unwritten lines are printed to the console instead of being thrown from log().

Option	Default	Meaning
withTime	true	Include a local timestamp with milliseconds in every line
filemode	'a'	'w' truncates the file on creation
cycles	50	Lines per disk write
cloudCycles	75	Waiting lines that wake the cloud sender
file	true	Write log lines to a file
consoleLevel	'DEBUG'	BasicLogger only; filters console output

Logger.log(message, { red, green, customPrefix, offConsole }) sets the line color, prefix, and console visibility.