tslog: Universal TypeScript Logger

Common errors

• Error [ERR_REQUIRE_ESM]: require() of ES Module C:\path\to\node_modules\tslog\dist\index.js not supported.

  cause Attempting to `require()` an ESM module (`tslog`) in a CommonJS context without proper interoperability settings or when the project is configured for ESM.
  fix For ESM projects, use `import { Logger } from 'tslog';`. For CJS projects that need to import an ESM module, you might need to use dynamic `import()` or configure `esModuleInterop: true` in `tsconfig.json` and adjust runtime environment if `type: module` is present in the dependency but not in your project. Alternatively, ensure Node.js is run in a CJS context for CJS bundle of tslog by explicitly calling `node dist/index.cjs` after compilation.

• TypeError: tslog.Logger is not a constructor

  cause This usually occurs in a browser environment when the `tslog` script has been loaded via a `<script>` tag, but the `Logger` class is attempted to be imported as an ESM module, or `tslog` global isn't correctly exposed.
  fix If loading `tslog` via a `<script>` tag, access `Logger` through the global `tslog` object: `const logger = new tslog.Logger();`. If using a build tool, ensure it correctly handles ESM imports for browser environments.

• Log messages show incorrect file names or line numbers in stack traces (e.g., pointing to `tslog` internal files or transpiled JS).

  cause Source map support is not correctly configured or enabled, preventing `tslog` from mapping back to your original TypeScript source code.
  fix Ensure `"sourceMap": true` is set in your `tsconfig.json`. When running your Node.js application, include the `--enable-source-maps` flag: `node --enable-source-maps dist/your-app.js`. For `ts-node`, use `--loader ts-node/esm` (ESM) or `--require ts-node/register` (CJS) with `--enable-source-maps`.

Warnings

• breaking In `v4.10.0`, the `transportFormatted` override function signature changed. It now receives `logMeta` as the fourth argument. Implementations that previously read `settings` from the fourth position need adjustment. Pass five parameters to also receive `settings`.
  Fix: Adjust custom `transportFormatted` functions to accept `logMeta` as the fourth argument. If `settings` are still required, ensure the function signature accepts five parameters.
• breaking As of `v4.10.0`, deprecated runtime entry points under `src/runtime/**` and related browser mappings have been removed. Direct imports from these paths will no longer work.
  Fix: Migrate imports to use the primary `Logger` export from `'tslog'` instead of specific runtime helpers (e.g., `import { Logger } from 'tslog';`).
• gotcha For accurate stack traces with TypeScript in Node.js, it is crucial to enable source maps. This requires configuring `sourceMap: true` in `tsconfig.json` and running Node.js with the `--enable-source-maps` flag.
  Fix: Ensure your `tsconfig.json` includes `"sourceMap": true`. When running your compiled Node.js application, use `node --enable-source-maps dist/index.js` or similar for correct stack information.
• gotcha When using `tslog` in a Node.js project, especially with TypeScript, it's recommended to set `"type": "module"` in your `package.json` for native ESM support. This affects how imports are resolved and how CommonJS modules interoperate.
  Fix: Add `"type": "module"` to your `package.json` for native ESM. If you must use CommonJS, consider using `.cjs` file extensions for CJS-specific files or ensure appropriate TypeScript `moduleResolution` and `module` options.
• gotcha By default, `tslog` is optimized for developer experience, which includes settings that might impact performance in production. For optimal production performance, review and adjust settings like `hideLogPositionForProduction`.
  Fix: In production environments, configure logger settings such as `hideLogPositionForProduction: true` to minimize overhead associated with collecting meta-information like code position.

Install

• npm install tslog npm
• yarn add tslog yarn
• pnpm add tslog pnpm

Imports

• Logger
  wrong:

  const { Logger } = require('tslog');

  correct:

  import { Logger } from 'tslog';

  ESM import is preferred. CommonJS require() works but may require specific TypeScript compiler options (e.g., `esModuleInterop: true`) or Node.js runtime flags if not configured as `type: module`.
• ILogObj
  wrong:

  import type { ILogObj } from 'tslog';

  correct:

  import { ILogObj } from 'tslog';

  ILogObj is an interface used for defining the structure of log objects. While `import type` is valid for type-only imports, a regular named import works correctly here as well.
• tslog (browser global)
  wrong:

  import { Logger } from 'tslog'; // in browser script tag without build tool

  correct:

  const logger = new tslog.Logger();

  When `tslog.js` is loaded directly in a browser via a script tag, the `Logger` class is exposed under the global `tslog` object. Direct ESM imports are not supported without a build step or browser-native ESM.

Quickstart

This quickstart demonstrates how to instantiate a `tslog` logger, configure its basic settings like log level and template, and use various logging methods. It also shows how to create a child logger for module-specific logging.

import { Logger, ILogObj } from "tslog";

// Create a new logger instance with optional configuration
const log: Logger<ILogObj> = new Logger({
  name: "myAppLogger",
  minLevel: 3, // info and above
  prettyLogTemplate: "{{logLevelName}} {{name}} " // Customize output template
});

// Log various messages
log.silly("This is a silly message and will not show with minLevel 3.");
log.trace("Tracing code execution.");
log.debug("Debugging a variable: ", { userId: 123, data: "test" });
log.info("Application started successfully.");
log.warn("Deprecated feature in use.");
log.error("An unexpected error occurred.", new Error("File not found"));
log.fatal("Critical system failure!");

// Example of a child logger for a specific module
const userModuleLog = log.getChildLogger({ name: "UserModule" });
userModuleLog.info("User 'admin' logged in.");