0
# Script Inlining
1

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

4
## Capabilities
5

6
### Inline Configuration
7

8
Configure scripts to be inlined directly into the HTML document for optimal loading performance.
9

10
```javascript { .api }
11
/**
12
 * Configure script inlining
13
 * @param pattern - Pattern(s) to match script files for inlining
14
 */
15
inline?: PatternConfig;
16

17
interface PatternConfig {
18
  test: string | RegExp | Array<string | RegExp>;
19
}
20
```
21

22
**Usage Examples:**
23

24
```javascript
25
// Inline a single script
26
new ScriptExtHtmlWebpackPlugin({
27
  inline: 'runtime.js'
28
})
29

30
// Inline multiple scripts
31
new ScriptExtHtmlWebpackPlugin({
32
  inline: ['runtime.js', 'polyfills.js']
33
})
34

35
// Pattern-based inlining
36
new ScriptExtHtmlWebpackPlugin({
37
  inline: /^runtime.*\.js$/
38
})
39

40
// Advanced configuration
41
new ScriptExtHtmlWebpackPlugin({
42
  inline: {
43
    test: ['runtime.js', /small.*\.js$/]
44
  }
45
})
46
```
47

48
### Asset Cleanup
49

50
Control whether inlined assets are removed from the webpack compilation output.
51

52
```javascript { .api }
53
/**
54
 * Whether to remove inlined assets from compilation
55
 * @default true
56
 */
57
removeInlinedAssets?: boolean;
58
```
59

60
**Usage Examples:**
61

62
```javascript
63
// Remove inlined assets (default behavior)
64
new ScriptExtHtmlWebpackPlugin({
65
  inline: 'runtime.js',
66
  removeInlinedAssets: true
67
})
68

69
// Keep inlined assets in output
70
new ScriptExtHtmlWebpackPlugin({
71
  inline: 'runtime.js',  
72
  removeInlinedAssets: false
73
})
74
```
75

76
### Inlining Process
77

78
The plugin inlines scripts by replacing `<script src="...">` tags with `<script>...</script>` tags containing the actual script content.
79

80
**Before inlining:**
81
```html
82
<script src="runtime.js"></script>
83
```
84

85
**After inlining:**
86
```html
87
<script>
88
// Webpack runtime code here
89
(function() { ... })();
90
</script>
91
```
92

93
### Best Practices for Inlining
94

95
**Ideal candidates for inlining:**
96
- Small runtime scripts
97
- Critical path scripts  
98
- Polyfills and feature detection
99
- Configuration scripts
100

101
**Not recommended for inlining:**
102
- Large application bundles
103
- Third-party libraries
104
- Scripts that benefit from caching
105

106
**Usage Examples:**
107

108
```javascript
109
// Inline critical scripts for performance
110
new ScriptExtHtmlWebpackPlugin({
111
  inline: ['runtime.js', 'critical.js'],
112
  async: /^(?!runtime|critical).*\.js$/,
113
  removeInlinedAssets: true
114
})
115

116
// Complex pattern example with multiple conditions
117
new ScriptExtHtmlWebpackPlugin({
118
  inline: ['runtime.js', /^small.*\.js$/],
119
  removeInlinedAssets: true
120
})
121
```
122

123
### Development Considerations
124

125
**Hot Module Replacement:**
126
Inlined scripts may not work properly with webpack's Hot Module Replacement (HMR). For development, consider disabling inlining or configuring html-webpack-plugin with caching disabled:
127

128
```javascript
129
// Development configuration
130
const isProduction = process.env.NODE_ENV === 'production';
131

132
new ScriptExtHtmlWebpackPlugin({
133
  inline: isProduction ? 'runtime.js' : []
134
})
135

136
// Or disable html-webpack-plugin caching
137
new HtmlWebpackPlugin({
138
  cache: false  // Required for HMR with inlined scripts
139
})
140
```
141

142
**Minification:**
143
Even simple scripts are wrapped with webpack boilerplate. Ensure JavaScript minification is enabled for legible HTML output:
144

145
```javascript
146
// Webpack production configuration
147
module.exports = {
148
  mode: 'production', // Enables minification
149
  plugins: [
150
    new ScriptExtHtmlWebpackPlugin({
151
      inline: 'runtime.js'
152
    })
153
  ]
154
};
155
```
156

157
### Error Handling
158

159
The plugin will throw a standard Error if a script specified for inlining cannot be found in the compilation assets.
160

161
```javascript { .api }
162
/**
163
 * Error thrown when inlined asset is not found
164
 * Uses standard Error class with descriptive message
165
 */
166
function throwInlineError(scriptName: string): void;
167
```
168

169
**Example error:**
170
```
171
ScriptExtHtmlWebpackPlugin: no asset with href 'missing-script.js'
172
```
173

174
The error is thrown during the `alterAssetTagsCallback` phase when the plugin attempts to inline a script that doesn't exist in the webpack compilation assets.
175

176
### Integration with Other Features
177

178
Inlining works in combination with other plugin features:
179

180
```javascript
181
// Complex configuration with inlining
182
new ScriptExtHtmlWebpackPlugin({
183
  inline: 'runtime.js',           // Inline runtime
184
  async: /chunk.*\.js$/,          // Async chunks  
185
  preload: 'critical.js',         // Preload critical
186
  custom: [{                      // Custom attributes
187
    test: /\.js$/,
188
    attribute: 'nonce',
189
    value: 'abc123'
190
  }],
191
  removeInlinedAssets: true
192
})
193
```
194

195
This configuration will:
196
1. Inline the runtime script directly into HTML
197
2. Make chunk scripts async
198
3. Add preload hints for critical scripts
199
4. Add nonce attributes to all scripts (including inlined ones)
200
5. Remove the inlined runtime.js from webpack output