0
# Script Extension for HTML Webpack Plugin
1

2
Script Extension for HTML Webpack Plugin is a webpack plugin that enhances html-webpack-plugin functionality by providing advanced script tag configuration options. It enables developers to add async, defer, and module attributes to script elements, supports script inlining, and provides resource hints (preload/prefetch) for optimizing JavaScript loading strategies.
3

4
## Package Information
5

6
- **Package Name**: script-ext-html-webpack-plugin
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install --save-dev script-ext-html-webpack-plugin`
10

11
## Core Imports
12

13
```javascript
14
const ScriptExtHtmlWebpackPlugin = require('script-ext-html-webpack-plugin');
15
```
16

17
Note: This package uses CommonJS exports and does not support ES6 import syntax.
18

19
## Basic Usage
20

21
```javascript
22
const HtmlWebpackPlugin = require('html-webpack-plugin');
23
const ScriptExtHtmlWebpackPlugin = require('script-ext-html-webpack-plugin');
24

25
module.exports = {
26
  plugins: [
27
    new HtmlWebpackPlugin(),
28
    new ScriptExtHtmlWebpackPlugin({
29
      defaultAttribute: 'async'
30
    })
31
  ]
32
};
33
```
34

35
**Important**: The plugin must be placed **after** HtmlWebpackPlugin in the plugins array.
36

37
## Architecture
38

39
Script Extension for HTML Webpack Plugin is built around several key components:
40

41
- **Plugin Class**: Main `ScriptExtHtmlWebpackPlugin` class that integrates with webpack's plugin system
42
- **Configuration System**: Normalizes and validates plugin options with sensible defaults
43
- **Element Processing**: Modifies script elements based on configured patterns and attributes
44
- **Resource Hints**: Generates preload/prefetch link tags for performance optimization
45
- **Asset Management**: Handles inlined script assets and cleanup during webpack emit phase
46

47
## Capabilities
48

49
### Plugin Configuration
50

51
Core plugin class and configuration options for controlling script element processing behavior.
52

53
```javascript { .api }
54
class ScriptExtHtmlWebpackPlugin {
55
  constructor(options?: PluginOptions);
56
  apply(compiler: object): void;
57
}
58

59
interface PluginOptions {
60
  async?: PatternConfig;
61
  defer?: PatternConfig;
62
  sync?: PatternConfig;
63
  module?: PatternConfig;
64
  inline?: PatternConfig;
65
  preload?: ResourceHintConfig;
66
  prefetch?: ResourceHintConfig;
67
  defaultAttribute?: 'sync' | 'async' | 'defer';
68
  removeInlinedAssets?: boolean;
69
  custom?: CustomAttributeConfig[];
70
}
71
```
72

73
[Plugin Configuration](./plugin-configuration.md)
74

75
### Script Attributes
76

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

79
```javascript { .api }
80
// Pattern matching for script attribute assignment
81
type PatternConfig = string | RegExp | Array<string | RegExp> | {
82
  test: string | RegExp | Array<string | RegExp>;
83
};
84
```
85

86
[Script Attributes](./script-attributes.md)
87

88
### Script Inlining
89

90
Inline script content directly into HTML instead of generating separate files, with automatic asset cleanup.
91

92
```javascript { .api }
93
interface InlineConfig {
94
  test: string | RegExp | Array<string | RegExp>;
95
}
96
```
97

98
[Script Inlining](./script-inlining.md)
99

100
### Resource Hints
101

102
Generate preload and prefetch link tags for initial and dynamically loaded scripts to optimize loading performance.
103

104
```javascript { .api }
105
interface ResourceHintConfig {
106
  test: string | RegExp | Array<string | RegExp>;
107
  chunks?: 'initial' | 'async' | 'all';
108
}
109
```
110

111
[Resource Hints](./resource-hints.md)
112

113
### Custom Attributes
114

115
Add arbitrary custom attributes to script elements for specialized use cases like CORS, CSP, or custom loading behavior.
116

117
```javascript { .api }
118
interface CustomAttributeConfig {
119
  test: string | RegExp | Array<string | RegExp>;
120
  attribute: string;
121
  value?: any;
122
}
123
```
124

125
[Custom Attributes](./custom-attributes.md)
126

127
## Types
128

129
### Core Types
130

131
```javascript { .api }
132
/**
133
 * Base pattern matching configuration
134
 */
135
interface PatternConfig {
136
  test: string | RegExp | Array<string | RegExp>;
137
}
138

139
/**
140
 * Resource hint configuration with chunk targeting
141
 */
142
interface ResourceHintConfig extends PatternConfig {
143
  chunks?: 'initial' | 'async' | 'all';
144
}
145

146
/**
147
 * Custom attribute configuration
148
 */
149
interface CustomAttributeConfig extends PatternConfig {
150
  attribute: string;
151
  value?: any;
152
}
153

154
/**
155
 * Complete plugin options interface
156
 */
157
interface PluginOptions {
158
  async?: PatternConfig;
159
  defer?: PatternConfig;
160
  sync?: PatternConfig;  
161
  module?: PatternConfig;
162
  inline?: PatternConfig;
163
  preload?: ResourceHintConfig;
164
  prefetch?: ResourceHintConfig;
165
  defaultAttribute?: 'sync' | 'async' | 'defer';
166
  removeInlinedAssets?: boolean;
167
  custom?: CustomAttributeConfig[];
168
}
169

170
/**
171
 * Pattern matching implementation details
172
 */
173
function matches(scriptName: string, patterns: Array<string | RegExp>): boolean;
174
```