Exframe Logger

Common errors

• Error: Cannot find module 'logger'

  cause Incorrect package name used in `require()` or `import` statement.
  fix Change `require('logger')` to `require('exframe-logger')` or `import ... from 'exframe-logger'`.

• TypeError: ExframeLogger.create is not a function

  cause The module was imported incorrectly, or `create` is not directly exposed as a method on the default export.
  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();`.

• SyntaxError: Cannot use import statement outside a module

  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).
  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();`.

Warnings

• gotcha 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.
  Fix: Always use `import ... from 'exframe-logger'` for ESM or `const ... = require('exframe-logger')` for CommonJS.
• breaking 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.
  Fix: Upgrade your Node.js runtime to version 14.0.0 or newer (e.g., using `nvm install 18` or `nvm use 18`).
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install exframe-logger npm
• yarn add exframe-logger yarn
• pnpm add exframe-logger pnpm

Imports

• Logger
  wrong:

  const Logger = require("logger").create();

  correct:

  import ExframeLogger from 'exframe-logger';
  const logger = ExframeLogger.create();

  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`.
• create
  wrong:

  import ExframeLogger from 'exframe-logger';
  const logger = ExframeLogger.create(); // not strictly wrong, but potentially less direct if 'create' is a named export

  correct:

  import { create } from 'exframe-logger';
  const logger = create();

  If `create` is a direct named export, this is the preferred ESM import. Some setups might require the default import pattern shown above.
• ExframeLoggerConfig

  import type { ExframeLoggerConfig } from 'exframe-logger';

  Type import for configuring the logger, useful for type-checking and autocompletion in TypeScript projects.

Quickstart

Demonstrates how to import and instantiate the Exframe Logger, then log messages across various severity levels with optional metadata.

import ExframeLogger from 'exframe-logger';

// Create a logger instance with default configuration (or pass an object for custom options)
const logger = ExframeLogger.create();

// Log messages at different levels
logger.info('Application started successfully.');
logger.debug('Database connection string: ' + process.env.DB_CONNECTION_STRING ?? 'default_connection');
logger.warn('Potential performance bottleneck detected.', { component: 'auth-service', durationMs: 1200 });
try {
  throw new Error('Failed to process user request');
} catch (error) {
  logger.error('An unhandled error occurred.', { 
    errorMessage: error.message,
    stack: error.stack,
    userId: 'user-123'
  });
}