Logger Utility

Configurable logger utility: debug tour state transitions, step changes, and lifecycle events in development mode

A configurable logger for userTourKit that adapts to your environment. Provides consistent logging with level-based filtering.

Why Use This Logger?

Environment-aware - Errors only in production, warnings in development
Configurable levels - Control verbosity at runtime
Consistent prefix - Easy to filter userTourKit logs
Zero overhead - Silent mode disables all logging

Usage

import { logger } from '@tour-kit/core';

// Basic logging
logger.debug('Debug info:', { state });
logger.info('Tour started:', tourId);
logger.warn('Element not found:', selector);
logger.error('Failed to save state:', error);

Log Levels

Prop

Type

Configuration

configure

Set the logger configuration.

import { logger } from '@tour-kit/core';

// Enable debug logging
logger.configure({ level: 'debug' });

// Custom prefix
logger.configure({ prefix: '[my-app]' });

// Disable logging in tests
logger.configure({ level: 'silent' });

Configuration Options

interface LoggerConfig {
  /** Minimum level to log. Default: 'warn' (dev) / 'error' (prod) */
  level: LogLevel
  /** Prefix for all log messages. Default: '[tour-kit]' */
  prefix: string
}

type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent'

Prop

Type

getConfig

Get the current configuration.

const config = logger.getConfig();
// { level: 'warn', prefix: '[tour-kit]' }

Environment Defaults

// Default in development
logger.configure({ level: 'warn' });

// Logged:
logger.warn('Warning message');  // ✓ Logged
logger.error('Error message');   // ✓ Logged

// Not logged:
logger.debug('Debug message');   // ✗ Skipped
logger.info('Info message');     // ✗ Skipped

// Default in production (NODE_ENV=production)
logger.configure({ level: 'error' });

// Logged:
logger.error('Error message');   // ✓ Logged

// Not logged:
logger.debug('Debug message');   // ✗ Skipped
logger.info('Info message');     // ✗ Skipped
logger.warn('Warning message');  // ✗ Skipped

Debug Mode

Enable verbose logging for troubleshooting:

import { logger } from '@tour-kit/core';

// Enable debug mode
logger.configure({ level: 'debug' });

// Now all levels are logged
logger.debug('Step rendered:', { stepId, rect });
logger.info('Tour started');
logger.warn('Fallback placement used');
logger.error('Storage unavailable');

Silent Mode

Disable all logging (useful for tests):

import { logger } from '@tour-kit/core';

// In test setup
beforeAll(() => {
  logger.configure({ level: 'silent' });
});

Custom Prefix

import { logger } from '@tour-kit/core';

// Multiple instances with different prefixes
logger.configure({ prefix: '[tour-kit:onboarding]' });
logger.info('Starting onboarding tour');
// Output: [tour-kit:onboarding] Starting onboarding tour

Internal Usage

userTourKit uses the logger internally for:

Scenario	Level	Example
Target element not found	`warn`	Element "#missing" not found
Storage operation failed	`warn`	Failed to save route state
Position calculation	`debug`	Calculated position: `{ x, y }`
advanceOn handler error	`warn`	advanceOn handler error for step "step-1"
State changes	`debug`	Tour state updated: `{ ... }`

API Reference

Logger Methods

interface Logger {
  // Configuration
  configure(config: Partial<LoggerConfig>): void;
  getConfig(): Readonly<LoggerConfig>;

  // Logging
  debug(...args: unknown[]): void;
  info(...args: unknown[]): void;
  warn(...args: unknown[]): void;
  error(...args: unknown[]): void;
}

LoggerConfig

interface LoggerConfig {
  level: 'debug' | 'info' | 'warn' | 'error' | 'silent';
  prefix?: string;
}

Best Practices

Development

// Enable debug mode during development
if (process.env.NODE_ENV === 'development') {
  logger.configure({ level: 'debug' });
}

Testing

// Silence logs in tests
describe('Tour', () => {
  beforeAll(() => {
    logger.configure({ level: 'silent' });
  });

  afterAll(() => {
    logger.configure({ level: 'warn' });
  });
});

Production

// Keep default (errors only) or silence completely
if (process.env.NODE_ENV === 'production') {
  logger.configure({ level: 'error' }); // or 'silent'
}

The logger automatically detects NODE_ENV=production and defaults to error-level logging.

Troubleshooting - Common issues and debugging
useAdvanceOn - Uses logger for handler errors
useRoutePersistence - Uses logger for storage errors

Logger Utility

On this page