Svelte SPA Router

Overview

The router includes a comprehensive debug logging system based on the loglevel library. It provides category-based logging with color-coded output and timestamps to help you troubleshoot routing issues during development.

The logging system has zero overhead when disabled - logs are complete no-ops at the silent level. Enable it only during development for debugging purposes.

Quick Start

Enable all debug logging in your main.js before mounting your app:

Enable debug logging

This will show all router debug messages in your browser console with color-coded output:

[14:23:45.123] [DEBUG] [ROUTER] Matched route: /user/:id
[14:23:45.234] [INFO] [ROUTER:NAVIGATION] Navigating to: /user/123
[14:23:45.345] [WARN] [ROUTER:GUARDS] Guard failed for route
[14:23:45.456] [ERROR] [ROUTER:ERROR_HANDLER] Unhandled error

Logging Categories

The router uses 12 hierarchical logging categories:

Category	Description	Use Case
`ROUTER`	Core routing pipeline and route matching	Debug route matching issues and pipeline flow
`ROUTER:NAVIGATION`	push, pop, replace, goBack functions	Track navigation function calls and parameters
`ROUTER:SCROLL`	Scroll restoration and position tracking	Debug scroll position save/restore issues
`ROUTER:GUARDS`	Navigation guard evaluation	Debug beforeLeave and route guard failures
`ROUTER:CONDITIONS`	Route condition/guard checks	Debug async route condition failures
`ROUTER:HIERARCHY`	Hierarchical route inheritance	Debug breadcrumb/permission inheritance
`ROUTER:PERMISSIONS`	Permission checking and authorization	Debug permission failures and auth callbacks
`ROUTER:ROUTES`	Named routes and URL building	Debug route registration and name resolution
`ROUTER:ZONES`	Multi-zone routing	Debug zone-specific route matching
`ROUTER:METADATA`	Breadcrumbs and route metadata	Debug metadata inheritance and updates
`ROUTER:ERROR_HANDLER`	Global error handling and recovery	Debug error recovery strategies
`ROUTER:FILTERS`	Querystring filter parsing	Debug filter extraction from querystrings

Configuration API

Enable All Logging

enableLogging()

Disable All Logging

disableLogging()

Set Global Log Level

setLogLevel(level)

Set Per-Category Log Level

setCategoryLevel(category, level)

Browser Console API

The router exposes a global API at window.components['svelte-spa-router'] for runtime debugging and introspection directly from your browser's DevTools console.

No code changes required! Toggle logging, check versions, and debug issues in production builds without modifying or rebuilding your application.

Check Library Version

Get the current router version at runtime:

Check version in production

View Package Metadata

Package metadata

Enable Logging from Console

Toggle debug logging on and off without code changes:

Toggle logging from console

Control Specific Categories

Per-category control from console

List Available Categories

List all categories

Practical Use Cases

Debug Production Issues:
User reports navigation not working? Open console and enable navigation logging: window.components['svelte-spa-router'].logging.setCategoryLevel('ROUTER:NAVIGATION', 'debug')

Test Permission Changes:
Testing permission logic? Enable permission logging on the fly: window.components['svelte-spa-router'].logging.setCategoryLevel('ROUTER:PERMISSIONS', 'debug')

Version Compatibility:
Check if the deployed version matches your expectations: window.components['svelte-spa-router'].version()

Explore Available Categories:
Not sure which category to enable? List them all: window.components['svelte-spa-router'].logging.getCategories()

Benefits

No rebuild required - Toggle logging in production builds
Runtime version checking - Verify deployed library version
Quick troubleshooting - Enable logging during user sessions
TypeScript support - Full autocompletion in browser console
SSR-safe - Only available in browser environment
Namespace-safe - Uses window.components shared namespace

Note: The global API is available only in browser environments. It will be undefined during server-side rendering (SSR).

Common Debugging Scenarios

Debug Route Not Found Issues

Route matching debugging

Debug Navigation Issues

Navigation debugging

Debug Permission Failures

Permission debugging

Debug Scroll Restoration

Scroll debugging

Output Format

All log messages follow a consistent format:

[HH:MM:SS.mmm] [LEVEL] [CATEGORY] message

Timestamp: High-resolution time in [HH:MM:SS.mmm] format
Level: TRACE, DEBUG, INFO, WARN, ERROR
Category: Hierarchical category name (e.g., ROUTER:NAVIGATION)
Message: Descriptive log message with relevant data

Color Coding

Level	Color	Use Case
DEBUG	■ Blue	Detailed diagnostic information
INFO	■ Green	General informational messages
WARN	■ Orange	Warning messages (potential issues)
ERROR	■ Red	Error messages (actual problems)

Best Practices

1. Enable Only in Development

2. Use Category-Specific Logging

Instead of enabling all logging, enable only the categories you need:

3. Different Levels for Different Categories

4. Configuration Warnings Always Visible

Critical configuration warnings and errors are always displayed using console.warn() and console.error(), regardless of logging configuration. These indicate serious misconfigurations that need immediate attention.

Performance

Zero overhead when disabled: When logging is disabled (default state or disableLogging()), all log calls are complete no-ops with negligible performance impact.

The logger uses the lightweight loglevel library (~1KB minified) with the loglevel-plugin-prefix extension for timestamps and formatting.

Library size: ~1KB (loglevel) + ~500B (prefix plugin)
Runtime overhead when disabled: <1μs per log call
No bundle size impact - tree-shaken in production builds

Implementation Details

Library Choice

The router uses loglevel as its logging foundation because it:

Is tiny (~1KB) and well-tested
Has zero dependencies
Supports log levels with proper filtering
Works identically in all browsers
Has excellent TypeScript support

Vendored Dependencies

The loglevel and loglevel-plugin-prefix libraries are vendored in src/lib/vendor/loglevel/ to ensure consistent behavior across all environments. This follows the same pattern as @keenmate/web-multiselect.

Logger Structure

All logger instances are exported from src/lib/logger.ts:

Troubleshooting

Logs Not Appearing

Verify logging is enabled: enableLogging() or setCategoryLevel(...)
Check browser console filters - ensure "Debug" level is visible
Verify import path: @keenmate/svelte-spa-router/logger
Check that you're calling logging config before app mount

Too Many Logs

Use setLogLevel('info') to reduce verbosity
Enable only specific categories with setCategoryLevel()
Disable categories you don't need