Changelog - 2026-11-01
One logger factory for the server, a script and a browser
Breaking ChangeIn one line. LoggerFactory.getLogger([scope]) is the one way to get a logger everywhere, and LoggerFactory.use({ provider, level }) chooses the provider and the level, with no setup needed for the console.
What changed
- Import
LoggerFactoryandConsoleLoggerfrom@venizia/ignis-helpers/core. The factory imports nothing from node. Browser bundles can use it directly. The default provider is the console. - Omit
LoggerFactory.usein compiled binaries.@venizia/ignisautomatically selects Winston duringinitialize(). It skips this selection if your app already picked a provider. The console remains active ifwinstonis not installed. - Call
LoggerFactory.use({ provider, level })to set the provider and the level. Use aLogLevelsvalue for the level. The level applies to every provider in the same way. - Pass the scope to
ConsoleLogger.getas a string.ConsoleLogger.get({ scope: 'x' })becomesConsoleLogger.get('x'), and it returns aConsoleLoggerwhere it returned anILogger. The codemod does not rewrite it: a direct call with the old object does not type-check, so the typecheck finds each one.ConsoleLoggerwas already public from the package root, so this changes code that calls it directly. - Check
LoggerDebugGate.isOpen()instead ofSHOULD_LOG_DEBUG.SHOULD_LOG_DEBUGis removed. It only recorded a snapshot when the module loaded. Loggers now check the live gate directly. You can update that live gate withLoggerFactory.use({ level }). Nothing inside IGNIS read the old constant. - Stop using removed symbols. The update removes
ApplicationLogger,LoggerSlot,LoggerResolver,ResolvedLoggerandTLoggerResolver. It also removes the warning about logging to the console with no provider installed.
Who is affected
- Apps that call
ApplicationLogger. Run the codemod. It converts those calls toLoggerFactory.getLogger([scope]). - Apps that use
LoggerSlot,LoggerResolver,TLoggerResolver, orLoggerSlot.usefrom prerelease0.4.7-1. Replace the resolver by callingLoggerFactory.use({ provider, level }). Convert any resolver that returned a customILoggerinto anILoggerProvider. Make it a class with a staticget(scope: string): ILoggermethod. - Scripts relying on the console warning, or apps calling
LoggerFactory.useonly for compiled binaries. The warning is gone. Theusecall is now optional. Keep the call only if you want Pino or need to set a specific level. - Everyone else. Do nothing.
Breaking changes
WARNING
Code that imports ApplicationLogger, LoggerSlot, LoggerResolver or TLoggerResolver fails to compile or to load after the upgrade.
Before:
typescript
import { ApplicationLogger } from '@venizia/ignis-helpers';
import { ConsoleLogger, LoggerSlot } from '@venizia/ignis-helpers/core';
const logger = ApplicationLogger.get({ scope: 'UserService' });
LoggerSlot.use({
resolver: ({ scopes }) => quietDebug(ConsoleLogger.get({ scope: scopes.join('-') })),
});After:
typescript
import { LoggerFactory, LogLevels } from '@venizia/ignis-helpers';
const logger = LoggerFactory.getLogger(['UserService']);
LoggerFactory.use({ level: LogLevels.INFO }); // debug lines are offTo upgrade:
- Run
devz codemod namespace-functions(dry run), then add--write. The logger rewrite is part of it: it movesApplicationLogger.get('x'),.get(NAME)and.get({ scope })toLoggerFactory.getLogger([...])and fixes the import. - Replace each
LoggerSlot.use({ resolver })withLoggerFactory.use({ provider, level }). The codemod does not touch it. - Run your typecheck after the codemod. An identifier argument is taken for a scope (
ApplicationLogger.get(NAME)becomesLoggerFactory.getLogger([NAME])), so one that held the old{ scope }object does not type-check, and a use ofApplicationLoggerthat is not a call (a type, a re-export, a value) is listed with its file and line for you to change. - Delete a
LoggerFactory.usethat only existed to keep a compiled binary from failing, unless it picks Pino.
Details
- Know the debug gate rules. Every provider shares the same rule. Debug is off by default. It turns on only when
DEBUGis truthy andNODE_ENVis unset or set to an allowed name. You can add allowed names withAPP_ENV_EXTRA_LOG_ENVS. Environments withoutprocess, such as a browser, keep debug off. - Override the gate with a level. Set
level: LogLevels.DEBUGto force debug on. Set any higher level to force debug off. The level setting overrides the environment variables. - Call
useat any time. Existing loggers switch to the new provider on their next log line. Call order does not matter. - Expect console format before
initialize().@venizia/ignisselects Winston wheninitialize()runs. Any line logged earlier uses console format. This includes lines logged in constructors or direct test calls. CallLoggerFactory.usebefore building the app if those early lines must go to Winston files. - Pass valid
LogLevelsvalues. The factory ignores any value outsideLogLevels. Typos or uppercase strings from environment variables change nothing. Invalid values never enable debug logging. - Write custom providers without custom debug gates. The factory filters out
debugmessages while the gate is closed. Custom providers do not need their own gate logic. - Use helper methods when needed. Call
LoggerFactory.useUnlessChosen({ provider })to set a fallback provider.@venizia/ignisuses this method for Winston. You can also inspect or clear state withisChosen()andreset(). - Read the startup warning when Winston is installed but broken. If
winstonis installed andinitialize()cannot load it for any reason other than "not installed",@venizia/ignisprints oneconsole.warnline and the console stays the logger:[ServerLoggerStartup] Winston could not be loaded, so the console stays the logger | cause: <message>. Fix the install (a broken package or a version mismatch) to get Winston files back. A missingwinstonstays silent. - Rely on shared state across duplicate bundles. The chosen provider and level live in
globalThisslots. Two copies of@venizia/ignis-helpersin the same bundle share the same configuration. - Configure scripts that import only helpers. These scripts default to the console. Call
LoggerFactory.use({ provider })withPinoLoggerorWinstonLoggerif you need another provider.
typescript
import { LoggerFactory, LogLevels } from '@venizia/ignis-helpers';
import { PinoLogger } from '@venizia/ignis-helpers/pino';
LoggerFactory.use({ provider: PinoLogger, level: LogLevels.INFO });The guide is on the logger page.