tessl/npm-script-ext-html-webpack-plugin

Enhances html-webpack-plugin functionality with async and defer attributes for script elements

—

Pending

Overview

Eval results

Files

Plugin Configuration

Name: tessl/npm-script-ext-html-webpack-plugin
Author: tessl

Core plugin class and configuration system for controlling script element processing behavior.

Capabilities

ScriptExtHtmlWebpackPlugin Class

Main plugin class that integrates with webpack's plugin system to enhance html-webpack-plugin functionality.

/**
 * Main plugin class for script element enhancement
 * @param options - Configuration options for the plugin
 */
class ScriptExtHtmlWebpackPlugin {
  constructor(options?: PluginOptions);
  apply(compiler: object): void;
}

Usage Examples:

const ScriptExtHtmlWebpackPlugin = require('script-ext-html-webpack-plugin');

// Basic usage with default options
new ScriptExtHtmlWebpackPlugin()

// With configuration options
new ScriptExtHtmlWebpackPlugin({
  defaultAttribute: 'async',
  defer: ['critical.js'],
  inline: 'runtime.js'
})

Plugin Options Interface

Complete configuration interface defining all available plugin options.

/**
 * Plugin configuration options
 */
interface PluginOptions {
  /** Configure async attribute application */
  async?: PatternConfig;
  /** Configure defer attribute application */
  defer?: PatternConfig;
  /** Configure sync script handling */
  sync?: PatternConfig;
  /** Configure module attribute application */
  module?: PatternConfig;
  /** Configure script inlining */
  inline?: PatternConfig;
  /** Configure preload resource hints */
  preload?: ResourceHintConfig;
  /** Configure prefetch resource hints */
  prefetch?: ResourceHintConfig;
  /** Default attribute for unmatched scripts */
  defaultAttribute?: 'sync' | 'async' | 'defer';
  /** Whether to remove inlined assets from compilation */
  removeInlinedAssets?: boolean;
  /** Array of custom attribute configurations */
  custom?: CustomAttributeConfig[];
}

Default Configuration

The plugin uses sensible defaults when no configuration is provided.

/**
 * Default plugin configuration
 */
const DEFAULT_OPTIONS = {
  inline: { test: [] },
  sync: { test: [] },
  async: { test: [] },
  defer: { test: [] },
  module: { test: [] },
  prefetch: { test: [], chunks: 'initial' },
  preload: { test: [], chunks: 'initial' },
  defaultAttribute: 'sync',
  removeInlinedAssets: true,
  custom: []
};

Configuration Examples:

// All scripts async by default
new ScriptExtHtmlWebpackPlugin({
  defaultAttribute: 'async'
})

// Specific script patterns with different attributes
new ScriptExtHtmlWebpackPlugin({
  sync: 'critical.js',
  async: ['chunk1.js', 'chunk2.js'],
  defer: /lazy.*\.js$/,
  defaultAttribute: 'async'
})

// Complex configuration with multiple options
new ScriptExtHtmlWebpackPlugin({
  inline: 'runtime.js',
  async: /^(?!runtime).*\.js$/,
  preload: {
    test: 'critical.js',
    chunks: 'initial'  
  },
  custom: [{
    test: /\.js$/,
    attribute: 'crossorigin',
    value: 'anonymous'
  }],
  removeInlinedAssets: true
})

Configuration Validation

The plugin validates configuration options and normalizes patterns for consistent processing.

/**
 * Normalizes and validates plugin options
 * @param options - Raw plugin options
 * @returns Normalized options object
 */
function normaliseOptions(options?: PluginOptions): NormalizedOptions;

Pattern Configuration Types

Base configuration types for pattern matching used throughout the plugin.

/**
 * Pattern configuration for matching scripts
 */
interface PatternConfig {
  test: string | RegExp | Array<string | RegExp>;
}

/**
 * Extended pattern configuration for resource hints
 */
interface ResourceHintConfig extends PatternConfig {
  chunks?: 'initial' | 'async' | 'all';
}

/**
 * Configuration for custom attributes
 */
interface CustomAttributeConfig extends PatternConfig {
  attribute: string;
  value?: any;
}

Webpack Integration

The plugin integrates with webpack through the standard plugin API and hooks into html-webpack-plugin events.

/**
 * Webpack plugin apply method - registers hooks with webpack compiler
 * @param compiler - Webpack compiler instance
 */
apply(compiler: object): void;

/**
 * Compilation callback that registers html-webpack-plugin hooks  
 * @param compilation - Webpack compilation instance
 */
compilationCallback(compilation: object): void;

/**
 * Main processing callback that modifies script tags
 * @param compilation - Webpack compilation instance
 * @param pluginArgs - Arguments from html-webpack-plugin containing headTags/bodyTags
 * @param callback - Completion callback for webpack 3.x and below
 */
alterAssetTagsCallback(
  compilation: object, 
  pluginArgs: object, 
  callback?: Function
): void;

/**
 * Emit callback that handles asset cleanup for inlined scripts
 * @param compilation - Webpack compilation instance
 * @param callback - Completion callback
 */
emitCallback(compilation: object, callback?: Function): void;

Install with Tessl CLI

npx tessl i tessl/npm-script-ext-html-webpack-plugin

docs

custom-attributes.md

index.md

plugin-configuration.md

tessl/npm-script-ext-html-webpack-plugin