The template includes a sophisticated centralized logging system with component-based filtering and automatic debug elimination.

Quick Start

Basic Usage

import { createLogger } from './utils/Logger';

class MyComponent {
    private logger = createLogger('myComponent');
    
    someMethod() {
        this.logger.debug('Method called', { data });
        this.logger.info('Operation completed');
        this.logger.warn('Warning message', error);
        this.logger.error('Error occurred', error);
    }
}

Features

Component-Based Logging

Each component gets its own logger with independent log level:

const logger = createLogger('modal');  // Component name

Available components:

Log Levels

Four log levels in order of severity:

  1. debug - Detailed diagnostic information
  2. info - General informational messages
  3. warn - Warning messages for potential issues
  4. error - Error messages for failures

Filtering:

Default Configuration

All components default to warn level:

const DEFAULT_CONFIG: LoggerConfig = {
    main: 'warn',
    modal: 'warn',
    api: 'warn',
    // ... etc
};

In development: Explicitly enable debug in main.ts:

if (typeof BUILD_ENV !== 'undefined' && BUILD_ENV === 'development') {
    logger.setComponentLevel('main', 'debug');
    logger.setComponentLevel('modal', 'debug');
    // ... enable for all components
}

Tag-Based Filtering

For complex components with lots of debug output, use tags:

// Enable only specific debug categories
logger.setComponentLevel('npe', 'debug', ['validation', 'state']);

// Use tags in debug calls
logger.debug('Field valid', { field }, ['validation']);  // ✅ Shows
logger.debug('Rendering', { time }, ['rendering']);      // ❌ Hidden

See: Tag-Based Filtering Guide

File Logging

Optional logging to file (debug-log.txt in vault root):

// Enable file logging (in main.ts)
logger.initFileLogging(this.app);

// Disable on plugin unload
logger.disableFileLogging();

Features:

Production Behavior

Automatic Debug Elimination

In production builds, all debug code is eliminated:

// Development: Full output
this.logger.debug('Processing', { data });

// Production: This line doesn't execute!
// Zero runtime overhead

How it works:

  1. BUILD_ENV constant replaced at build time
  2. isDevelopment() returns false in production
  3. Debug method returns early
  4. Tree-shaking removes unreachable code

Result:

Preserved Logging

info, warn, and error remain in production:

this.logger.info('Plugin loaded');    // ✅ Shows in production
this.logger.warn('Deprecated API');   // ✅ Shows in production
this.logger.error('Failed to load');  // ✅ Shows in production

API Reference

createLogger(component)

Creates a component-specific logger:

const logger = createLogger('componentName');

Returns: ComponentLogger with methods:

logger.debug(message, data?, tags?)

Log debug message (eliminated in production):

this.logger.debug('User clicked button', { 
    buttonId: 'submit',
    timestamp: Date.now() 
}, ['user-interaction']);

Parameters:

logger.info(message, data?)

Log informational message:

this.logger.info('Settings saved', { 
    settingCount: 5 
});

logger.warn(message, data?)

Log warning message:

this.logger.warn('Deprecated API used', {
    api: 'oldMethod',
    replacement: 'newMethod'
});

logger.error(message, data?)

Log error message:

this.logger.error('Failed to load data', error);

Configuration Methods

setComponentLevel(component, level, tags?)

Set log level for a component:

logger.setComponentLevel('modal', 'debug');
logger.setComponentLevel('npe', 'debug', ['validation']);

setConfig(config)

Set configuration for multiple components:

logger.setConfig({
    main: 'debug',
    modal: 'debug',
    ui: 'info'
});

setEnabled(enabled)

Enable/disable all logging:

logger.setEnabled(false);  // Silence all logs

Best Practices

Use Appropriate Levels

// ✅ Debug: Detailed diagnostic info
this.logger.debug('Validating field', { field, value });

// ✅ Info: General events
this.logger.info('Modal opened');

// ✅ Warn: Potential issues
this.logger.warn('Slow operation detected', { duration });

// ✅ Error: Failures
this.logger.error('API request failed', error);

Include Context

// ❌ Not helpful
this.logger.debug('Processing');

// ✅ Helpful
this.logger.debug('Processing user input', {
    fieldName: 'email',
    valueLength: value.length,
    isValid: true
});

Use Tags for Complex Components

// In a large component with multiple concerns
this.logger.debug('Validation passed', { field }, ['validation']);
this.logger.debug('Rendering complete', { time }, ['rendering']);
this.logger.debug('State updated', { state }, ['state']);

// Enable only what you need
logger.setComponentLevel('component', 'debug', ['validation']);

Don’t Elevate Debug to Warn

// ❌ Wrong: This will show in production!
this.logger.warn('Debug info:', data);

// ✅ Right: Use debug level
this.logger.debug('Debug info:', data);

// ✅ Right: Use tags to filter noise
this.logger.debug('Debug info:', data, ['specific-tag']);

Troubleshooting

Debug Messages Not Showing

Check log level:

// In main.ts, ensure debug is enabled
if (BUILD_ENV === 'development') {
    logger.setComponentLevel('yourComponent', 'debug');
}

Check component name matches:

// Must match exactly
createLogger('modal')  // Component name
logger.setComponentLevel('modal', 'debug')  // Same name

Too Much Debug Output

Use tag filtering:

logger.setComponentLevel('npe', 'debug', ['validation']);

Or raise level temporarily:

logger.setComponentLevel('noisy-component', 'info');

File Logging Not Working

Enable in main.ts:

logger.initFileLogging(this.app);

Check vault root: