tessl/npm-ice--app

A universal framework based on React.js that provides scripts and configuration for web development with zero-config support for ES6+, TypeScript, routing, state management, and multi-platform deployment.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Logging Utilities

Name: tessl/npm-ice--app
Author: tessl

Ice.js provides a sophisticated logging system with namespace support and debug controls for development and production environments. The logging system is built on top of consola with additional features for better debugging experience.

Capabilities

Create Logger

Creates a namespaced logger instance with debug controls and intelligent filtering.

/**
 * Creates a namespaced logger instance
 * @param namespace - Optional namespace for the logger (supports wildcards)
 * @returns Logger instance with all logging methods
 */
function createLogger(namespace?: string): Logger;

Usage Examples:

import { createLogger } from "@ice/app";

// Default logger (no namespace)
const logger = createLogger();
logger.info('Application started');

// Namespaced logger
const dbLogger = createLogger('database');
dbLogger.debug('Database query executed');

// Component-specific logger
const componentLogger = createLogger('component:user-list');
componentLogger.warn('Component re-rendered');

Default Logger

Pre-configured logger instance ready for immediate use.

/**
 * Default logger instance without namespace
 */
const logger: Logger;

Usage Examples:

import { logger } from "@ice/app";

logger.start('Build process starting...');
logger.success('Build completed successfully');
logger.error('Build failed with error:', error);

Logger Interface

Complete interface for all logger instances with support for different log levels.

interface Logger {
  /** Fatal level logging - for critical errors that stop execution */
  fatal(message: any, ...args: any[]): void;
  /** Error level logging - for errors that don't stop execution */
  error(message: any, ...args: any[]): void;
  /** Warning level logging - for potential issues */
  warn(message: any, ...args: any[]): void;
  /** Standard logging - for general information */
  log(message: any, ...args: any[]): void;
  /** Info level logging - for informational messages */
  info(message: any, ...args: any[]): void;
  /** Start event logging - for process start notifications */
  start(message: any, ...args: any[]): void;
  /** Success event logging - for successful operations */
  success(message: any, ...args: any[]): void;
  /** Ready event logging - for readiness notifications */
  ready(message: any, ...args: any[]): void;
  /** Debug level logging - for debugging information */
  debug(message: any, ...args: any[]): void;
  /** Trace level logging - for detailed execution traces */
  trace(message: any, ...args: any[]): void;
  /** Brief error logging with instructions for detailed errors */
  briefError(message: any, ...args: any[]): void;
}

Debug Control

The logging system supports debug controls through the DEBUG_TAG environment variable, allowing you to filter logs by namespace.

Environment Variables

# Enable all debug logs
DEBUG_TAG=* npm start

# Enable specific namespace
DEBUG_TAG=database npm start

# Enable multiple namespaces
DEBUG_TAG=database,component:* npm start

# Disable specific namespace
DEBUG_TAG=*,-component:user-list npm start

Namespace Patterns

The debug system supports wildcard patterns similar to the debug library:

// Enable all component logs
DEBUG_TAG=component:*

// Enable specific component
DEBUG_TAG=component:user-list

// Enable multiple patterns
DEBUG_TAG=database,component:*,service:auth

// Disable specific patterns
DEBUG_TAG=*,-component:legacy-*

Advanced Usage

Brief Error Logging

The briefError method provides user-friendly error messages with instructions for viewing detailed error information:

import { createLogger } from "@ice/app";

const logger = createLogger('build');

try {
  // Some operation that might fail
  await buildProject();
} catch (error) {
  // Shows brief error and instructions for detailed debugging
  logger.briefError('Build failed', error);
  // Output: "Build failed [error details]"
  // If DEBUG_TAG is not set: "run `DEBUG_TAG=build npm run start` to view error details"
}

Logger Integration in Plugins

Logger can be used effectively in Ice.js plugins:

import { createLogger } from "@ice/app";

const logger = createLogger('plugin:my-plugin');

export default function myPlugin() {
  return {
    setup({ onHook }) {
      logger.info('Plugin initialized');
      
      onHook('before:compile', () => {
        logger.debug('Starting compilation...');
      });
      
      onHook('after:compile', () => {
        logger.success('Compilation completed');
      });
    }
  };
}

Development vs Production

The logging system automatically adjusts behavior based on the environment:

Development: All logs are shown by default
Production: Only logs matching DEBUG_TAG patterns are shown
Brief errors: Always provide debug instructions when DEBUG_TAG is not set

Type Definitions

type ICELogNamespace = string;
type CreateLogger = (namespace?: ICELogNamespace) => Logger;

interface CreateLoggerReturnType extends Logger {
  briefError?: (message: any, ...args: any[]) => void;
}