{"id":12198,"library":"tslog","title":"tslog: Universal TypeScript Logger","description":"tslog is an extensible logging library designed for both Node.js and browser environments, written in TypeScript. Currently stable at version 4.10.2, it maintains an active release cadence with frequent updates and bug fixes, often addressing compatibility and build issues. Key differentiators include its universal compatibility (Node.js, Browsers, Deno, Bun), full TypeScript support with native source map integration for accurate stack traces, and flexible output options (pretty or JSON). It also handles circular structures, supports sub-loggers, allows object and error interpolation, and features masking for sensitive data, making it suitable for a wide range of application logging needs. The library has zero external dependencies, promoting a lightweight footprint.","status":"active","version":"4.10.2","language":"javascript","source_language":"en","source_url":"https://github.com/fullstack-build/tslog","tags":["javascript","logger","typescript","log level","json","stacktrace","Error.stack","call location","debug"],"install":[{"cmd":"npm install tslog","lang":"bash","label":"npm"},{"cmd":"yarn add tslog","lang":"bash","label":"yarn"},{"cmd":"pnpm add tslog","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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`.","wrong":"const { Logger } = require('tslog');","symbol":"Logger","correct":"import { Logger } from 'tslog';"},{"note":"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.","wrong":"import type { ILogObj } from 'tslog';","symbol":"ILogObj","correct":"import { ILogObj } from 'tslog';"},{"note":"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.","wrong":"import { Logger } from 'tslog'; // in browser script tag without build tool","symbol":"tslog (browser global)","correct":"const logger = new tslog.Logger();"}],"quickstart":{"code":"import { Logger, ILogObj } from \"tslog\";\n\n// Create a new logger instance with optional configuration\nconst log: Logger<ILogObj> = new Logger({\n  name: \"myAppLogger\",\n  minLevel: 3, // info and above\n  prettyLogTemplate: \"{{logLevelName}} {{name}} \" // Customize output template\n});\n\n// Log various messages\nlog.silly(\"This is a silly message and will not show with minLevel 3.\");\nlog.trace(\"Tracing code execution.\");\nlog.debug(\"Debugging a variable: \", { userId: 123, data: \"test\" });\nlog.info(\"Application started successfully.\");\nlog.warn(\"Deprecated feature in use.\");\nlog.error(\"An unexpected error occurred.\", new Error(\"File not found\"));\nlog.fatal(\"Critical system failure!\");\n\n// Example of a child logger for a specific module\nconst userModuleLog = log.getChildLogger({ name: \"UserModule\" });\nuserModuleLog.info(\"User 'admin' logged in.\");","lang":"typescript","description":"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."},"warnings":[{"fix":"Adjust custom `transportFormatted` functions to accept `logMeta` as the fourth argument. If `settings` are still required, ensure the function signature accepts five parameters.","message":"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`.","severity":"breaking","affected_versions":">=4.10.0"},{"fix":"Migrate imports to use the primary `Logger` export from `'tslog'` instead of specific runtime helpers (e.g., `import { Logger } from 'tslog';`).","message":"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.","severity":"breaking","affected_versions":">=4.10.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=4.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=4.0.0"},{"fix":"In production environments, configure logger settings such as `hideLogPositionForProduction: true` to minimize overhead associated with collecting meta-information like code position.","message":"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`.","severity":"gotcha","affected_versions":">=4.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"Attempting to `require()` an ESM module (`tslog`) in a CommonJS context without proper interoperability settings or when the project is configured for ESM.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module C:\\path\\to\\node_modules\\tslog\\dist\\index.js not supported."},{"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.","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.","error":"TypeError: tslog.Logger is not a constructor"},{"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`.","cause":"Source map support is not correctly configured or enabled, preventing `tslog` from mapping back to your original TypeScript source code.","error":"Log messages show incorrect file names or line numbers in stack traces (e.g., pointing to `tslog` internal files or transpiled JS)."}],"ecosystem":"npm"}