Getting Started

This page installs Logaria and walks you through your first logger. For what Logaria is and the three parts you can opt in to, see Introduction; for the problem it solves, see Why Logaria.

Runtime Support

Logaria targets ESM-compatible runtimes:

• Node.js: ^20.19.0 || >=22.12.0
• Browsers: any modern browser served through an ESM-aware bundler
• Module format: ESM only ("type": "module")

The bundler plugin is built on unplugin and ships adapters for Vite, Rollup, Rolldown, esbuild, webpack, Rspack, and Farm.

Installation

pnpm

pnpm add logaria

npm

npm install logaria

yarn

yarn add logaria

bun

bun add logaria

Peer dependency for Rollup hosts

If you plan to use loggerPlugin.rollup(...), also install @rollup/plugin-replace. Other adapters use the bundler's native define hook and need no peer dependency.

Your First Logger

Configure the default scope, create a main logger, then derive a group logger before you log:

import { createLogger, resetLoggerConfig, setLoggerConfig } from 'logaria';
import { createElapsedTimer, formatErrorMessage } from 'logaria/helper';

setLoggerConfig({
  debug: true,
  levels: ['info', 'success', 'warn', 'error'],
});

const logger = createLogger({
  main: '@acme/docs',
}).getLoggerByGroup('build.pipeline');

logger.info('build started');

const elapsed = createElapsedTimer();

try {
  await build();
  logger.success('build finished', elapsed());
} catch (error) {
  logger.error(`build failed: ${formatErrorMessage(error)}`, elapsed());
  throw error;
}

logger.warn('cache is cold');
logger.debug('debug details');

resetLoggerConfig();

What each piece does:

• createLogger({ main }) names the package or subsystem that owns the log stream.
• .getLoggerByGroup(group) names a narrower area inside that stream.
• setLoggerConfig() / resetLoggerConfig() adjust the default scope at runtime. Use them only when your application owns the default scope.

Naming Conventions

A clear main and group is what lets rules target the right logs.

• main — the package or subsystem identity, usually the package name (@acme/docs, @scope/cli, app).
• group — a lowercase dot namespace inside that stream. Do not repeat the package name.

Good group values: runtime.react, build.pipeline, dev.hmr, userland.metrics.

Configuration Ownership

Logaria has one default scope behind the root entry and optional explicit scopes for host integrations. Choose the owner before creating loggers — see Core Concepts — Ownership and Scopes for the full model:

Situation	Entry	Config owner
Direct app, script, or package runtime	logaria	The application calls setLoggerConfig() / resetLoggerConfig().
Bundler-controlled runtime	logaria + logaria/plugin	The bundler plugin injects the default scope config.
Host integration with private ownership	logaria/core	The host registers an explicit scope before calling createScopedLogger().
Formatting and elapsed-time helpers	logaria/helper	No runtime config.
Scope helper utilities	logaria/core/helper	No runtime config.

Library authors

Reusable libraries should not call setLoggerConfig() or resetLoggerConfig() at module initialization. The default scope belongs to the application or bundler host that owns the runtime. Libraries that need private visibility should use scoped integrations instead.

Next Steps

• Tour the capabilities with examples — Features
• Learn the model behind it — Core Concepts
• Tune which logs print — Runtime Config
• Match logs by main, group, message — Rules & Presets
• Strip suppressed calls from production — Bundler Plugin
• Own a private scope from a host package — Scoped Integrations
• Look up every export — API Reference

Runtime Demo

The demo below imports the real logaria package from this docs site. Pick a profile and run the scenario to see the captured console output.

Runtime logger demo

Default visibility keeps info, success, warn, and error; debug stays hidden.

Active config

null

Captured output

Run a scenario to capture logger output here.