tessl/npm-fortawesome--fontawesome-svg-core

The Font Awesome SVG JavaScript library for programmatic icon rendering and DOM manipulation

—

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

Configuration

Name: tessl/npm-fortawesome--fontawesome-svg-core
Author: tessl

Global configuration object for customizing Font Awesome behavior. The configuration system provides fine-grained control over icon rendering, DOM operations, performance settings, and automatic behaviors.

Capabilities

Config Object

Global configuration interface providing comprehensive control over Font Awesome behavior.

/**
 * Global configuration interface for Font Awesome behavior
 */
interface Config {
  /** CSS class prefix for Font Awesome families (default: 'fa') */
  familyPrefix: string;
  /** CSS class prefix for Font Awesome icons (default: 'fa') */
  cssPrefix: string;
  /** Default icon style when none specified */
  styleDefault: IconPrefix | CssStyleClass | IconStyle;
  /** Default icon family when none specified */
  familyDefault: IconFamily;
  /** CSS class name for replaced elements (default: 'svg-inline--fa') */
  replacementClass: string;
  /** Enable automatic SVG replacement (default: true) */
  autoReplaceSvg: boolean | 'nest';
  /** Automatically inject Font Awesome CSS (default: true) */
  autoAddCss: boolean;
  /** Search for pseudo-elements to replace (default: true) */
  searchPseudoElements: boolean;
  /** Show warnings for pseudo-element replacement (default: true) */
  searchPseudoElementsWarnings: boolean;
  /** Use full document scan for pseudo-elements (default: false) */
  searchPseudoElementsFullScan: boolean;
  /** Watch for DOM mutations and auto-replace (default: true) */
  observeMutations: boolean;
  /** Keep original source attributes in replaced elements (default: true) */
  keepOriginalSource: boolean;
  /** Enable performance measurement logging (default: false) */
  measurePerformance: boolean;
  /** DOM mutation approach for performance (default: 'async') */
  mutateApproach: "async" | "sync";
  /** Show console warnings for missing icons (default: true) */
  showMissingIcons: boolean;
}

/**
 * Global configuration instance
 */
const config: Config;

Basic Configuration

Essential configuration options for common use cases.

Default Style and Family:

import { config } from "@fortawesome/fontawesome-svg-core";

// Set default icon style
config.styleDefault = 'fas';     // Default to solid icons
config.familyDefault = 'classic'; // Default to classic family

// Now icons without explicit prefix use these defaults
const icon = icon('home'); // Uses 'fas' prefix automatically

CSS Prefix Customization:

// Customize CSS class prefixes
config.familyPrefix = 'custom-fa';  // Changes 'fa-' to 'custom-fa-'
config.cssPrefix = 'icon';          // Changes 'fa-' to 'icon-'

// Resulting classes: 'custom-fa-solid', 'icon-home', etc.

Replacement Class:

// Customize the CSS class for replaced SVG elements
config.replacementClass = 'custom-svg-icon';

// SVG elements will have class 'custom-svg-icon' instead of 'svg-inline--fa'

Automatic Behavior Control

Configuration options for automatic Font Awesome features.

// Automatic replacement settings
autoReplaceSvg: boolean | 'nest';
autoAddCss: boolean;
observeMutations: boolean;

Auto-Replace SVG:

// Control automatic SVG replacement
config.autoReplaceSvg = true;   // Enable automatic replacement
config.autoReplaceSvg = false;  // Disable automatic replacement
config.autoReplaceSvg = 'nest'; // Use nested SVG approach

// Disable automatic replacement for manual control
config.autoReplaceSvg = false;
// Must manually call dom.i2svg()

Auto-Add CSS:

// Control automatic CSS injection
config.autoAddCss = true;  // Automatically inject CSS
config.autoAddCss = false; // Manual CSS management required

// With autoAddCss disabled, manually add CSS
if (!config.autoAddCss) {
  const css = dom.css();
  // Manually inject or serve CSS
}

Mutation Observation:

// Control DOM mutation watching
config.observeMutations = true;  // Watch for new icons
config.observeMutations = false; // No automatic watching

// With mutations disabled, new icons require manual replacement
config.observeMutations = false;
// dom.watch() will not function

Performance Configuration

Settings for optimizing Font Awesome performance in different environments.

// Performance-related settings
mutateApproach: "async" | "sync";
measurePerformance: boolean;
keepOriginalSource: boolean;

Mutation Approach:

// Choose DOM mutation strategy
config.mutateApproach = 'async'; // Better for large apps (default)
config.mutateApproach = 'sync';  // Better for small apps or SSR

// Async approach prevents UI blocking
config.mutateApproach = 'async';

Performance Measurement:

// Enable performance monitoring
config.measurePerformance = true;

// Performance data will be logged to console
// Useful for optimization and debugging

Source Preservation:

// Control whether original element attributes are preserved
config.keepOriginalSource = true;  // Preserve data-* attributes
config.keepOriginalSource = false; // Remove original attributes

// With keepOriginalSource enabled:
// <i class="fas fa-home" data-custom="value"></i>
// becomes:
// <svg class="svg-inline--fa fa-home" data-custom="value">...</svg>

Pseudo-Element Configuration

Settings for CSS pseudo-element icon replacement.

// Pseudo-element replacement settings
searchPseudoElements: boolean;
searchPseudoElementsWarnings: boolean;
searchPseudoElementsFullScan: boolean;

Pseudo-Element Search:

// Control pseudo-element replacement
config.searchPseudoElements = true;  // Enable pseudo-element search
config.searchPseudoElements = false; // Disable pseudo-element search

// Enable warnings for pseudo-element issues
config.searchPseudoElementsWarnings = true;

// Use full document scan (performance impact)
config.searchPseudoElementsFullScan = false; // Default: selective scan
config.searchPseudoElementsFullScan = true;  // Full document scan

Error and Warning Configuration

Control warning and error message display.

// Warning and error settings
showMissingIcons: boolean;

Missing Icon Warnings:

// Control warnings for missing icons
config.showMissingIcons = true;  // Show warnings (default)
config.showMissingIcons = false; // Suppress warnings

// With warnings enabled, missing icons log to console:
// "Could not find icon with iconName=missing-icon and prefix=fas"

Disable Automatic Features

Completely disable Font Awesome's automatic behaviors for manual control.

/**
 * Disable all automatic Font Awesome behaviors
 */
function noAuto(): void;

Complete Manual Control:

import { noAuto, dom, library, icon } from "@fortawesome/fontawesome-svg-core";

// Disable all automatic behaviors
noAuto();
// Equivalent to:
// config.autoReplaceSvg = false;
// config.autoAddCss = false;
// config.observeMutations = false;

// Now everything must be done manually
library.add(faHome);
const homeIcon = icon('home');
document.body.innerHTML = homeIcon.html[0];
dom.insertCss(); // Manual CSS injection

Configuration Patterns

Common configuration patterns for different use cases.

High-Performance Configuration:

// Optimize for performance in large applications
config.mutateApproach = 'async';
config.measurePerformance = true;
config.keepOriginalSource = false;
config.searchPseudoElementsFullScan = false;
config.observeMutations = true; // Keep for convenience

Server-Side Rendering Configuration:

// Configuration for SSR environments
config.autoReplaceSvg = false;  // Manual replacement
config.autoAddCss = false;      // CSS handled by bundler
config.observeMutations = false; // No DOM watching on server
config.mutateApproach = 'sync'; // Synchronous for SSR

Development Configuration:

// Enhanced debugging and warnings for development
config.measurePerformance = true;
config.showMissingIcons = true;
config.searchPseudoElementsWarnings = true;
config.keepOriginalSource = true; // Preserve debugging info

Production Configuration:

// Optimized for production deployment
config.measurePerformance = false;
config.showMissingIcons = false; // Suppress console warnings
config.keepOriginalSource = false; // Reduce DOM size
config.mutateApproach = 'async'; // Non-blocking updates

Environment Detection

Adapting configuration based on the runtime environment.

// Environment-based configuration
if (typeof window !== 'undefined') {
  // Browser environment
  config.autoReplaceSvg = true;
  config.observeMutations = true;
} else {
  // Server environment
  config.autoReplaceSvg = false;
  config.observeMutations = false;
}

// Development vs production
if (process.env.NODE_ENV === 'development') {
  config.measurePerformance = true;
  config.showMissingIcons = true;
} else {
  config.measurePerformance = false;
  config.showMissingIcons = false;
}