Skip to main content

​
Overview

The log module provides a comprehensive set of logging utilities for Scully applications. It includes colored console output, severity-based filtering, file logging, and progress indicators for long-running operations.

​
Logging Functions

​
log

Standard logging for informational messages. 
function log(...args: any[]): void
Example: 
import { log } from '@scullyio/scully';

log('Starting Scully build...');
log('Found', routeCount, 'routes');

​
logOk

Logs success messages with a green checkmark (✔). 
function logOk(...args: any[]): void
Example: 
import { logOk } from '@scullyio/scully';

logOk('Successfully rendered all pages');
logOk('Build completed in', duration, 'seconds');

​
logWarn

Logs warning messages with an orange warning symbol (⚠) and orange text. 
function logWarn(...args: any[]): void
Example: 
import { logWarn } from '@scullyio/scully';

logWarn('Route contains unescaped parameters');
logWarn('Using experimental feature');

​
logError

Logs error messages with a red cross (✗) and red text. Also captures errors for telemetry. 
function logError(...args: any[]): void
Example: 
import { logError } from '@scullyio/scully';

logError('Failed to render route:', route);
logError('Plugin not found:', pluginName);

​
logWrite

Logs messages with the same severity as errors (for filtering purposes) but without the error icon. 
function logWrite(...args: any[]): void
Example: 
import { logWrite } from '@scullyio/scully';

logWrite('Writing output to:', outputPath);

​
Progress Indicators

Scully provides utilities for showing progress during long-running operations.

​
startProgress

Starts an animated spinner that indicates work is in progress. 
function startProgress(): void

​
stopProgress

Stops the progress spinner and clears the line. 
function stopProgress(): void

​
printProgress

Displays a progress counter with customizable text. 
function printProgress(
  tasks: number | boolean,
  text?: string,
  total?: number
): void
​
tasks
number | boolean
required
The number of remaining tasks, or a boolean flag
​
text
string
default:"Tasks Left:"
Custom text to display before the count
​
total
number
Optional total number of tasks (displays as “tasks/total”)
Example: 
import { startProgress, printProgress, stopProgress } from '@scullyio/scully';

startProgress();

for (let i = routes.length; i > 0; i--) {
  printProgress(i, 'Routes remaining:', routes.length);
  await renderRoute(routes[routes.length - i]);
}

stopProgress();

​
Log Severity Levels

Scully supports filtering logs by severity level via CLI options. 
enum LogSeveritys {
  normal,    // Standard informational messages
  ok,        // Success messages
  warning,   // Warning messages
  error,     // Error messages
  none       // No logging
}
You can control the log level using the --log-severity CLI option: 
scully --log-severity=error    # Only show errors
scully --log-severity=warning  # Show warnings and errors
scully --log-severity=none     # Suppress all logs

​
Color Utilities

The module exports color utilities for custom formatting: 
import { orange, white, red, yellow, green } from '@scullyio/scully';

console.log(orange('This text is orange'));
console.log(green('This text is green'));
console.log(red('This text is red'));
These are chalk functions for terminal coloring.

​
File Logging

All logs are automatically written to scully.log in your project root (where angular.json is located). ANSI color codes are stripped from file logs for readability.
File logging respects the --log-severity setting. If severity is set to none, file logging is disabled.

​
Usage Examples

​
Basic Logging in a Plugin

import { registerPlugin, log, logError, logWarn } from '@scullyio/scully';

const myPlugin = async (html: string) => {
  log('Processing HTML with myPlugin');
  
  try {
    if (!html) {
      logWarn('Empty HTML content received');
      return html;
    }
    
    // Process HTML...
    const result = transform(html);
    
    log('Successfully processed HTML');
    return result;
  } catch (error) {
    logError('Failed to process HTML:', error.message);
    throw error;
  }
};

registerPlugin('render', 'myPlugin', myPlugin);

​
Progress Tracking

import {
  log,
  logOk,
  startProgress,
  printProgress,
  stopProgress
} from '@scullyio/scully';

async function buildRoutes(routes: string[]) {
  log(`Building ${routes.length} routes`);
  
  startProgress();
  
  for (let i = 0; i < routes.length; i++) {
    const remaining = routes.length - i;
    printProgress(remaining, 'Routes remaining:', routes.length);
    
    await processRoute(routes[i]);
  }
  
  stopProgress();
  logOk(`All ${routes.length} routes built successfully`);
}

​
Conditional Logging

import { log, logWarn, logError } from '@scullyio/scully';

function processConfig(config: any) {
  if (config.experimental) {
    logWarn('Using experimental configuration options');
  }
  
  if (!config.routes) {
    logError('Configuration missing required "routes" property');
    throw new Error('Invalid configuration');
  }
  
  log('Configuration validated successfully');
}

​
Custom Colored Output

import { log, orange, yellow, green } from '@scullyio/scully';

function displayStats(stats: BuildStats) {
  log('\nBuild Statistics:');
  log(green('  ✓ Successful:'), stats.successful);
  log(yellow('  ⚠ Warnings:'), stats.warnings);
  log(orange('  ✗ Failed:'), stats.failed);
  log('\nTotal time:', stats.duration, 'ms');
}

​
Best Practices

Use the appropriate log level for your message:
  • log for informational messages
  • logOk for successful operations
  • logWarn for non-critical issues
  • logError for failures and errors
Avoid excessive logging in tight loops. Use printProgress for iteration updates instead of logging each iteration.
In CI environments where process.stdout.cursorTo is unavailable, progress indicators are automatically disabled to prevent output pollution.

​
Common Use Cases

Plugin Development

Add informative logging to custom plugins for debugging and user feedback

Build Progress

Show progress indicators during route rendering and file generation

Error Handling

Log errors with proper severity for troubleshooting

Configuration Validation

Provide warnings for deprecated or experimental features

Creating Plugins

Learn how to create plugins with proper logging

CLI Options

Explore CLI options for controlling log output

​
Source Code

Location: libs/scully/src/lib/utils/log.ts:1

Build docs developers (and LLMs) love

Get started for freeTalk to us