{"id":10857,"library":"exframe-logger","title":"Exframe Logger","description":"Exframe Logger is a foundational logging module designed for the Harmony Framework, built on top of the popular Winston logging library. It provides a structured approach to application-level logging, offering standard log levels such as `debug`, `info`, `warn`, and `error`. Currently at version 3.8.7, the package generally follows a stable release cadence with patch updates for bug fixes and minor improvements. Its key differentiator is its integration within the Exframe ecosystem, providing a consistent logging experience for applications leveraging other Exframe modules. Developers looking for a robust, Winston-backed logger within a structured framework context will find it suitable, though it can also be used standalone. It ships with TypeScript types, promoting better developer experience and type safety.","status":"active","version":"3.8.7","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","typescript"],"install":[{"cmd":"npm install exframe-logger","lang":"bash","label":"npm"},{"cmd":"yarn add exframe-logger","lang":"bash","label":"yarn"},{"cmd":"pnpm add exframe-logger","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core logging engine and transport management.","package":"winston","optional":false}],"imports":[{"note":"The primary way to instantiate a logger. The package likely exports a module object as default, with a 'create' method. Ensure you use the correct package name `exframe-logger`, not just `logger`.","wrong":"const Logger = require(\"logger\").create();","symbol":"Logger","correct":"import ExframeLogger from 'exframe-logger';\nconst logger = ExframeLogger.create();"},{"note":"If `create` is a direct named export, this is the preferred ESM import. Some setups might require the default import pattern shown above.","wrong":"import ExframeLogger from 'exframe-logger';\nconst logger = ExframeLogger.create(); // not strictly wrong, but potentially less direct if 'create' is a named export","symbol":"create","correct":"import { create } from 'exframe-logger';\nconst logger = create();"},{"note":"Type import for configuring the logger, useful for type-checking and autocompletion in TypeScript projects.","symbol":"ExframeLoggerConfig","correct":"import type { ExframeLoggerConfig } from 'exframe-logger';"}],"quickstart":{"code":"import ExframeLogger from 'exframe-logger';\n\n// Create a logger instance with default configuration (or pass an object for custom options)\nconst logger = ExframeLogger.create();\n\n// Log messages at different levels\nlogger.info('Application started successfully.');\nlogger.debug('Database connection string: ' + process.env.DB_CONNECTION_STRING ?? 'default_connection');\nlogger.warn('Potential performance bottleneck detected.', { component: 'auth-service', durationMs: 1200 });\ntry {\n  throw new Error('Failed to process user request');\n} catch (error) {\n  logger.error('An unhandled error occurred.', { \n    errorMessage: error.message,\n    stack: error.stack,\n    userId: 'user-123'\n  });\n}\n","lang":"typescript","description":"Demonstrates how to import and instantiate the Exframe Logger, then log messages across various severity levels with optional metadata."},"warnings":[{"fix":"Always use `import ... from 'exframe-logger'` for ESM or `const ... = require('exframe-logger')` for CommonJS.","message":"The README example `require(\"logger\")` is misleading. The correct package name for importing is `exframe-logger`. Using `logger` directly will result in a 'module not found' error unless `logger` is a symlink or an alias in your project.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Upgrade your Node.js runtime to version 14.0.0 or newer (e.g., using `nvm install 18` or `nvm use 18`).","message":"The package requires Node.js version 14.0.0 or higher. Older Node.js versions will encounter syntax errors or fail to install due to engine restrictions.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Configure the logger's level during instantiation (e.g., `ExframeLogger.create({ level: 'debug' })`) or via environment variables if the library supports it, to ensure desired log levels are captured.","message":"By default, `exframe-logger` might only log 'info' level and above, depending on its internal Winston configuration. Debug messages may not appear in production or even development environments without explicit configuration.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Refer to the `exframe-logger` documentation for custom transport setup or advanced configuration options. If specific Winston features are needed directly, consider using Winston independently.","message":"While built on Winston, direct access to underlying Winston transports or advanced configurations might require understanding Exframe Logger's abstraction layer. Don't assume direct Winston API compatibility without consulting documentation.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Change `require('logger')` to `require('exframe-logger')` or `import ... from 'exframe-logger'`.","cause":"Incorrect package name used in `require()` or `import` statement.","error":"Error: Cannot find module 'logger'"},{"fix":"Ensure you are importing the default export correctly (e.g., `import ExframeLogger from 'exframe-logger'; const logger = ExframeLogger.create();`) or if `create` is a named export, use `import { create } from 'exframe-logger'; const logger = create();`.","cause":"The module was imported incorrectly, or `create` is not directly exposed as a method on the default export.","error":"TypeError: ExframeLogger.create is not a function"},{"fix":"Either convert your project to use ES Modules by adding `\"type\": \"module\"` to your `package.json` and updating file extensions, or use CommonJS `require()` syntax: `const ExframeLogger = require('exframe-logger'); const logger = ExframeLogger.create();`.","cause":"Attempting to use ES module `import` syntax in a CommonJS context (e.g., in a `.js` file without `\"type\": \"module\"` in `package.json` or without `.mjs` extension).","error":"SyntaxError: Cannot use import statement outside a module"}],"ecosystem":"npm"}