A small helper around @logtape/logtape for applications that want logging to work out of the box with minimal setup. It comes with a built-in console sink as the default app-friendly sink, so in the common case you only need to set LOG_LEVEL to enable logging. (You can still add additional sinks when necessary.)

It follows one simple rule:

• if LOG_LEVEL is a valid log level, console logging is enabled at that level
• if LOG_LEVEL is missing or empty, console logging is disabled
• if LOG_LEVEL is invalid, console logging is disabled and a warning is emitted

logtape-easy also re-exports everything from @logtape/logtape, so you do not need to install @logtape/logtape separately.

This package is mainly intended for apps. If you are building a library, you usually do not need this package. You can install @logtape/logtape directly and call getLogger() in your library code.

Installation

npm install logtape-easy
# or
pnpm add logtape-easy
# or
yarn add logtape-easy
# or
bun add logtape-easy
# or
deno add npm:logtape-easy

Quick start

Synchronous setup

Use this when your environment does not support top-level await or when you want logging configured immediately at startup.

import { getLogger, setupLoggerSync } from 'logtape-easy'

setupLoggerSync()

const logger = getLogger(['app'])
logger.info('Hello')

Asynchronous setup

If your application already supports async startup, you can also use the async API:

import { getLogger, setupLogger } from 'logtape-easy'

await setupLogger()

const logger = getLogger(['app'])
logger.info('Hello')

How configuration is resolved

By default, logtape-easy reads the log level in this order:

1. localStorage.getItem('LOG_LEVEL')
2. process.env.LOG_LEVEL

This makes browser-side overrides easy while still working naturally in server-side runtimes.

Behavior summary

| Value | Result | |---|---| | missing | console logging disabled | | "" or whitespace | console logging disabled | | valid log level like info | console logging enabled at info level | | uppercase like DEBUG | console logging enabled at debug level | | invalid value | console logging disabled + warning |

Browser usage

Enable logging from DevTools:

localStorage.setItem('LOG_LEVEL', 'debug')

Disable it:

localStorage.removeItem('LOG_LEVEL')

Reload the page after changing the value.

Server-side usage

Set LOG_LEVEL in the environment:

LOG_LEVEL=info node dist/index.js

If the runtime does not provide localStorage or process.env, the library safely falls back.

API

setupLogger(options?)

Under the hood, it builds the LogTape config and applies it with configure({ reset: true, ... }).

import { setupLogger } from 'logtape-easy'

await setupLogger()

setupLoggerSync(options?)

Synchronous version of setupLogger().

Caution: setupLoggerSync() can only be used with sinks and filters that do not require asynchronous disposal.setupLoggerSync() can only be used with sinks and filters that do not require asynchronous disposal. Reference the LogTape docs for more details.

buildLoggerConfig(options?)

Returns the LogTape config without applying it.

import { buildLoggerConfig, configure } from 'logtape-easy'

const config = buildLoggerConfig()

await configure({
  reset: true,
  ...config,
})

Options

interface SetupLoggerOptions {
  sinks?: Record<string, Sink>
  loggers?: LoggerConfig[]
  filters?: Record<string, FilterLike>
  consoleSinkOptions?: ConsoleSinkOptions
  storage?: StorageLike
  env?: EnvLike
  preferenceKey?: string
  rootLevel?: LogLevel | null
  metaConsoleLevel?: LogLevel | null
  onWarn?: (message: string) => void
}

sinks

Attach additional sinks beside the built-in console sink, such as Sentry, OTEL, file sinks, etc.

import { getSentrySink } from '@logtape/sentry'

await setupLogger({
  sinks: {
    sentry: getSentrySink()
  },
})

loggers

The additional loggers to configure. They will not overwrite the built-in loggers, i.e. root and meta loggers.

filters

The filters to use.

consoleSinkOptions

Pass options to the built-in console sink. Reference ConsoleSinkOptions for the options details.

storage

Override storage access. (Default: localStorage)

await setupLogger({
  storage: {
    getItem: key => (key === 'LOG_LEVEL' && import.meta.dev ? 'debug' : null)
  },
})

env

Override environment access. (Default: process.env)

await setupLogger({
  env: {
    LOG_LEVEL: process.env.NODE === 'producation' ? 'info' : 'debug',
  },
})

preferenceKey

Use a different configuration key. (Default: LOG_LEVEL)

await setupLogger({
  preferenceKey: 'APP_LOG_LEVEL',
  env: {
    APP_LOG_LEVEL: 'debug',
  },
})

rootLevel

Sets the root logger minimum level when at least one sink is attached. (Default: trace)

metaConsoleLevel

Sets the LogTape meta logger level for the built-in console sink. (Default: warning)

onWarn

Called when the configured log level is invalid. (Default: console.warn)

Built-in console sink

The built-in console sink is intended to cover the most common logging setup with minimal configuration.

• set LOG_LEVEL to enable it
• leave LOG_LEVEL unset to disable it
• add sinks only when you need extra destinations beyond the console

Re-exports

logtape-easy re-exports LogTape:

export * from '@logtape/logtape'

So this works:

import { getConsoleSink, getLogger, setupLogger } from 'logtape-easy'

You do not need to install @logtape/logtape separately.

Example with a custom sink

import type { Sink } from 'logtape-easy'
import { getLogger, setupLogger } from 'logtape-easy'

const records: unknown[] = []

const memorySink: Sink = {
  write(record) {
    records.push(record)
  },
}

await setupLogger({
  env: { LOG_LEVEL: 'debug' },
  sinks: {
    memory: memorySink,
  },
})

const logger = getLogger(['example'])
logger.info('hello')

Contributing

Contributions are welcome! If you have ideas, bug fixes, or improvements, please open an issue or submit a pull request on the GitHub repository.

Give a ⭐️ if this project helped you!

License

This project is licensed under the MIT License. See the LICENSE file for more details.