0
# Plugin Configuration
1

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

4
## Capabilities
5

6
### ScriptExtHtmlWebpackPlugin Class
7

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

10
```javascript { .api }
11
/**
12
 * Main plugin class for script element enhancement
13
 * @param options - Configuration options for the plugin
14
 */
15
class ScriptExtHtmlWebpackPlugin {
16
  constructor(options?: PluginOptions);
17
  apply(compiler: object): void;
18
}
19
```
20

21
**Usage Examples:**
22

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

26
// Basic usage with default options
27
new ScriptExtHtmlWebpackPlugin()
28

29
// With configuration options
30
new ScriptExtHtmlWebpackPlugin({
31
  defaultAttribute: 'async',
32
  defer: ['critical.js'],
33
  inline: 'runtime.js'
34
})
35
```
36

37
### Plugin Options Interface
38

39
Complete configuration interface defining all available plugin options.
40

41
```javascript { .api }
42
/**
43
 * Plugin configuration options
44
 */
45
interface PluginOptions {
46
  /** Configure async attribute application */
47
  async?: PatternConfig;
48
  /** Configure defer attribute application */
49
  defer?: PatternConfig;
50
  /** Configure sync script handling */
51
  sync?: PatternConfig;
52
  /** Configure module attribute application */
53
  module?: PatternConfig;
54
  /** Configure script inlining */
55
  inline?: PatternConfig;
56
  /** Configure preload resource hints */
57
  preload?: ResourceHintConfig;
58
  /** Configure prefetch resource hints */
59
  prefetch?: ResourceHintConfig;
60
  /** Default attribute for unmatched scripts */
61
  defaultAttribute?: 'sync' | 'async' | 'defer';
62
  /** Whether to remove inlined assets from compilation */
63
  removeInlinedAssets?: boolean;
64
  /** Array of custom attribute configurations */
65
  custom?: CustomAttributeConfig[];
66
}
67
```
68

69
### Default Configuration
70

71
The plugin uses sensible defaults when no configuration is provided.
72

73
```javascript { .api }
74
/**
75
 * Default plugin configuration
76
 */
77
const DEFAULT_OPTIONS = {
78
  inline: { test: [] },
79
  sync: { test: [] },
80
  async: { test: [] },
81
  defer: { test: [] },
82
  module: { test: [] },
83
  prefetch: { test: [], chunks: 'initial' },
84
  preload: { test: [], chunks: 'initial' },
85
  defaultAttribute: 'sync',
86
  removeInlinedAssets: true,
87
  custom: []
88
};
89
```
90

91
**Configuration Examples:**
92

93
```javascript
94
// All scripts async by default
95
new ScriptExtHtmlWebpackPlugin({
96
  defaultAttribute: 'async'
97
})
98

99
// Specific script patterns with different attributes
100
new ScriptExtHtmlWebpackPlugin({
101
  sync: 'critical.js',
102
  async: ['chunk1.js', 'chunk2.js'],
103
  defer: /lazy.*\.js$/,
104
  defaultAttribute: 'async'
105
})
106

107
// Complex configuration with multiple options
108
new ScriptExtHtmlWebpackPlugin({
109
  inline: 'runtime.js',
110
  async: /^(?!runtime).*\.js$/,
111
  preload: {
112
    test: 'critical.js',
113
    chunks: 'initial'  
114
  },
115
  custom: [{
116
    test: /\.js$/,
117
    attribute: 'crossorigin',
118
    value: 'anonymous'
119
  }],
120
  removeInlinedAssets: true
121
})
122
```
123

124
### Configuration Validation
125

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

128
```javascript { .api }
129
/**
130
 * Normalizes and validates plugin options
131
 * @param options - Raw plugin options
132
 * @returns Normalized options object
133
 */
134
function normaliseOptions(options?: PluginOptions): NormalizedOptions;
135
```
136

137
### Pattern Configuration Types
138

139
Base configuration types for pattern matching used throughout the plugin.
140

141
```javascript { .api }
142
/**
143
 * Pattern configuration for matching scripts
144
 */
145
interface PatternConfig {
146
  test: string | RegExp | Array<string | RegExp>;
147
}
148

149
/**
150
 * Extended pattern configuration for resource hints
151
 */
152
interface ResourceHintConfig extends PatternConfig {
153
  chunks?: 'initial' | 'async' | 'all';
154
}
155

156
/**
157
 * Configuration for custom attributes
158
 */
159
interface CustomAttributeConfig extends PatternConfig {
160
  attribute: string;
161
  value?: any;
162
}
163
```
164

165
### Webpack Integration
166

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

169
```javascript { .api }
170
/**
171
 * Webpack plugin apply method - registers hooks with webpack compiler
172
 * @param compiler - Webpack compiler instance
173
 */
174
apply(compiler: object): void;
175

176
/**
177
 * Compilation callback that registers html-webpack-plugin hooks  
178
 * @param compilation - Webpack compilation instance
179
 */
180
compilationCallback(compilation: object): void;
181

182
/**
183
 * Main processing callback that modifies script tags
184
 * @param compilation - Webpack compilation instance
185
 * @param pluginArgs - Arguments from html-webpack-plugin containing headTags/bodyTags
186
 * @param callback - Completion callback for webpack 3.x and below
187
 */
188
alterAssetTagsCallback(
189
  compilation: object, 
190
  pluginArgs: object, 
191
  callback?: Function
192
): void;
193

194
/**
195
 * Emit callback that handles asset cleanup for inlined scripts
196
 * @param compilation - Webpack compilation instance
197
 * @param callback - Completion callback
198
 */
199
emitCallback(compilation: object, callback?: Function): void;
200
```