Amplify CLI Logger

1.2.3 verified Sat Apr 25 auth: no javascript

Amplify CLI Logger v1.2.3 is a logging utility internal to the AWS Amplify CLI ecosystem. It provides structured logging for Amplify CLI commands and plugins, with support for multiple log levels and output formatting. Released as part of the AWS Amplify CLI monorepo, it is tightly coupled to the Amplify CLI runtime and is not intended for standalone use. The package ships TypeScript types and is distributed via npm under the @aws-amplify scope. It is currently in active development alongside the Amplify CLI, with releases aligned to the CLI's major version (currently v14.x). Key differentiators include integration with Amplify CLI's context object and automatic log level configuration based on CLI verbosity settings.

Common errors

error Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/node_modules/@aws-amplify/amplify-cli-logger/dist/index.js from /path/to/project/index.js not supported. ↓

cause The package is ESM-only and cannot be loaded with require().

fix

Change the import to use ESM syntax: import { AmplifyLogger } from '@aws-amplify/amplify-cli-logger'; Or use dynamic import: const { AmplifyLogger } = await import('@aws-amplify/amplify-cli-logger');

error TypeError: Cannot read properties of undefined (reading 'info') ↓

cause Default import results in undefined because the package only exports named exports.

fix

Use named import: import { AmplifyLogger } from '@aws-amplify/amplify-cli-logger'; instead of default import.

error TS2339: Property 'LogLevels' does not exist on type 'typeof import("@aws-amplify/amplify-cli-logger")'. ↓

cause Incorrect enum name: 'LogLevels' instead of 'LogLevel'.

fix

Use LogLevel instead: import { LogLevel } from '@aws-amplify/amplify-cli-logger';

Warnings

breaking The package is ESM-only starting from v1.2.0. require() will throw a MODULE_NOT_FOUND error. ↓

fix Use import statements or dynamic import(). If you must use CommonJS, use a dynamic import wrapper: const { AmplifyLogger } = await import('@aws-amplify/amplify-cli-logger');

deprecated Constructor parameter 'logLevel' was renamed from 'level' in v1.1.0. ↓

fix Replace { level: LogLevel.INFO } with { logLevel: LogLevel.INFO }.

gotcha The logger is not designed for direct instantiation outside Amplify CLI context. It expects an AmplifyContext object with specific properties. ↓

fix Use getAmplifyLogger() factory function instead which properly initializes the logger with the current CLI context.

gotcha LogLevel enum values are strings ('DEBUG', 'INFO', 'WARN', 'ERROR'), not numbers. Comparing with === will work correctly but type narrowing may behave differently.

Install

npm install amplify-cli-logger

yarn add amplify-cli-logger

pnpm add amplify-cli-logger

Imports

AmplifyLogger

wrong

import AmplifyLogger from '@aws-amplify/amplify-cli-logger'

correct

import { AmplifyLogger } from '@aws-amplify/amplify-cli-logger'

This is a named export, not a default export. Using default import will result in undefined.

LogLevel

wrong

import { LogLevels } from '@aws-amplify/amplify-cli-logger'

correct

import { LogLevel } from '@aws-amplify/amplify-cli-logger'

The enum is named LogLevel, not LogLevels. Available values: DEBUG, INFO, WARN, ERROR.

getAmplifyLogger

wrong

const { getAmplifyLogger } = require('@aws-amplify/amplify-cli-logger')

correct

import { getAmplifyLogger } from '@aws-amplify/amplify-cli-logger'

This package is ESM-only. require() will fail unless you use a compatible Node version with esm resolution.

Quickstart

Shows creating a logger instance with configurable log level, logging messages at different levels including structured metadata, and proper cleanup.

import { AmplifyLogger, LogLevel } from '@aws-amplify/amplify-cli-logger';

const logger = new AmplifyLogger({
  logLevel: process.env.VERBOSE ? LogLevel.DEBUG : LogLevel.INFO,
  outputStream: process.stdout
});

logger.info('Amplify CLI initialized', { timestamp: new Date().toISOString() });
logger.debug('Verbose debugging info', { details: 'some context' });

try {
  // risky operation
  throw new Error('Operation failed');
} catch (err) {
  logger.error('An error occurred', { error: (err as Error).message });
}

// Cleanup
logger.close();