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

Script Attributes

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

Apply standard HTML script attributes (async, defer, module) to webpack-generated script tags based on configurable patterns.

Capabilities

Async Attribute

Configure scripts to load asynchronously without blocking HTML parsing.

/**
 * Configure async attribute application
 * @param pattern - Pattern(s) to match script files for async loading
 */
async?: PatternConfig;

interface PatternConfig {
  test: string | RegExp | Array<string | RegExp>;
}

Usage Examples:

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

// Specific scripts async
new ScriptExtHtmlWebpackPlugin({
  async: 'chunk1.js'
})

// Multiple scripts async
new ScriptExtHtmlWebpackPlugin({
  async: ['chunk1.js', 'chunk2.js']
})

// Pattern-based async
new ScriptExtHtmlWebpackPlugin({
  async: /chunk.*\.js$/
})

// Advanced configuration
new ScriptExtHtmlWebpackPlugin({
  async: {
    test: [/^chunk/, 'vendor.js']
  }
})

Defer Attribute

Configure scripts to defer execution until after document parsing is complete.

/**
 * Configure defer attribute application
 * @param pattern - Pattern(s) to match script files for deferred loading
 */
defer?: PatternConfig;

Usage Examples:

// Single script deferred
new ScriptExtHtmlWebpackPlugin({
  defer: 'analytics.js'
})

// Multiple scripts deferred
new ScriptExtHtmlWebpackPlugin({
  defer: ['analytics.js', 'tracking.js']
})

// Pattern-based defer
new ScriptExtHtmlWebpackPlugin({
  defer: /^(?!critical).*\.js$/
})

// Mixed configuration
new ScriptExtHtmlWebpackPlugin({
  sync: 'critical.js',
  defer: ['analytics.js', 'tracking.js'],
  defaultAttribute: 'async'
})

Module Attribute

Configure scripts to load as ES6 modules with type="module".

/**
 * Configure module attribute application
 * @param pattern - Pattern(s) to match script files for module loading
 */
module?: PatternConfig;

Usage Examples:

// ES6 module scripts
new ScriptExtHtmlWebpackPlugin({
  module: 'app.mjs'
})

// Multiple module scripts
new ScriptExtHtmlWebpackPlugin({
  module: ['app.mjs', 'utils.mjs']
})

// Pattern-based modules
new ScriptExtHtmlWebpackPlugin({
  module: /\.mjs$/
})

Sync Attribute

Explicitly configure scripts to load synchronously (default behavior).

/**
 * Configure sync script handling
 * @param pattern - Pattern(s) to match script files for synchronous loading
 */
sync?: PatternConfig;

Usage Examples:

// Ensure critical scripts remain sync when default is async
new ScriptExtHtmlWebpackPlugin({
  sync: 'critical.js',
  defaultAttribute: 'async'
})

// Multiple sync scripts
new ScriptExtHtmlWebpackPlugin({
  sync: ['critical.js', 'polyfills.js'],
  defaultAttribute: 'defer'
})

Default Attribute

Set the default loading behavior for scripts that don't match any specific patterns.

/**
 * Default attribute for unmatched scripts
 */
defaultAttribute?: 'sync' | 'async' | 'defer';

Usage Examples:

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

// All scripts deferred by default, except critical
new ScriptExtHtmlWebpackPlugin({
  sync: 'critical.js',
  defaultAttribute: 'defer'
})

// Sync by default (standard behavior)
new ScriptExtHtmlWebpackPlugin({
  defaultAttribute: 'sync'  // This is the default
})

Pattern Matching

The plugin supports flexible pattern matching for script selection.

/**
 * Pattern types supported for script matching
 */
type PatternConfig = 
  | string                              // Exact filename match
  | RegExp                              // Regular expression match
  | Array<string | RegExp>              // Array of patterns
  | { test: string | RegExp | Array<string | RegExp> }; // Object form

Pattern Examples:

// String pattern - exact match
async: 'bundle.js'

// RegExp pattern - flexible matching
async: /chunk.*\.js$/

// Array patterns - multiple matches
async: ['chunk1.js', 'chunk2.js', /vendor/]

// Object form - explicit test property
async: {
  test: [/chunk/, 'bundle.js']
}

// Complex patterns
new ScriptExtHtmlWebpackPlugin({
  inline: 'runtime.js',
  sync: [/imp(1|2){1,3}/, 'initial'],
  defer: ['slow', /big.*andslow/],
  module: [/^((?!sync).)*/, 'mod'],
  defaultAttribute: 'async'
})

Script Processing Order

The plugin uses a precedence model to ensure consistent behavior when multiple patterns match the same script:

Inline: If a script matches the inline pattern, it will be inlined (highest priority)
Sync: If a script matches the sync pattern, it will have no attribute, unless it matched condition 1
Async: If a script matches the async pattern, it will have the async attribute, unless it matched conditions 1 or 2
Defer: If a script matches the defer pattern, it will have the defer attribute, unless it matched conditions 1, 2, or 3
Default attribute: If a script doesn't match any previous conditions, it gets the defaultAttribute

The module attribute is independent of conditions 2-5, but will be ignored if the script is inlined.

Precedence Example:

new ScriptExtHtmlWebpackPlugin({
  inline: 'app.js',      // Takes precedence - script will be inlined
  sync: 'app.js',        // Ignored - inline takes precedence
  async: 'app.js',       // Ignored - inline takes precedence
  defaultAttribute: 'defer' // Applied to other scripts
})

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