0
# Asset Management
1

2
This document covers the programmatic interface for managing manifest entries, including methods for adding, retrieving, updating, and deleting asset mappings.
3

4
## Asset Storage Interface
5

6
```typescript { .api }
7
class WebpackAssetsManifest {
8
  // Asset storage
9
  assets: AssetsStorage;
10
  assetNames: Map<string, string>;
11
  
12
  // Core methods
13
  set(key: AssetsStorageKey, value: AssetsStorageValue): this;
14
  setRaw(key: AssetsStorageKey, value: AssetsStorageValue): this;
15
  get(key: AssetsStorageKey, defaultValue?: AssetsStorageValue): AssetsStorageValue | undefined;
16
  has(key: AssetsStorageKey): boolean;
17
  delete(key: AssetsStorageKey): boolean;
18
  clear(): void;
19
  
20
  // Utility methods
21
  fixKey(key: AssetsStorageKey): AssetsStorageKey;
22
  getExtension(filename: string): string;
23
  getPublicPath(filename: string): string;
24
  getOutputPath(): string;
25
  
26
  // Serialization methods
27
  toJSON(): AssetsStorage;
28
  toString(): string;
29
  
30
  // File operations
31
  writeTo(destination: string): Promise<void>;
32
  
33
  // Additional public methods
34
  processAssetsByChunkName(assets: StatsCompilation['assetsByChunkName'], hmrFiles: Set<string>): void;
35
  shouldWriteToDisk(compilation: Compilation): boolean;
36
  inDevServer(): boolean;
37
  
38
  // Proxy interface
39
  getProxy(raw?: boolean): this & { [key: AssetsStorageKey]: AssetsStorageValue };
40
}
41
```
42

43
## Adding Assets
44

45
### set() Method
46

47
Adds an asset to the manifest with full processing through the customize hook:
48

49
```typescript { .api }
50
set(key: AssetsStorageKey, value: AssetsStorageValue): this;
51
```
52

53
```typescript
54
// Add a simple asset mapping
55
manifest.set("main.js", "main-abc123.js");
56

57
// Add with complex value (when integrity is enabled)
58
manifest.set("styles.css", {
59
  src: "styles-def456.css",
60
  integrity: "sha256-xyz789...",
61
});
62
```
63

64
### setRaw() Method
65

66
Adds an asset without processing through hooks:
67

68
```typescript { .api }
69
setRaw(key: AssetsStorageKey, value: AssetsStorageValue): this;
70
```
71

72
```typescript
73
// Bypass all processing
74
manifest.setRaw("vendor.js", "vendor-ghi789.js");
75
```
76

77
## Retrieving Assets
78

79
### get() Method
80

81
Retrieves an asset value with optional default:
82

83
```typescript { .api }
84
get(key: AssetsStorageKey, defaultValue?: AssetsStorageValue): AssetsStorageValue | undefined;
85
```
86

87
```typescript
88
// Get asset value
89
const mainJs = manifest.get("main.js");
90

91
// Get with default value
92
const fallback = manifest.get("missing.js", "default.js");
93
```
94

95
### has() Method
96

97
Checks if an asset exists in the manifest:
98

99
```typescript { .api }
100
has(key: AssetsStorageKey): boolean;
101
```
102

103
```typescript
104
if (manifest.has("main.js")) {
105
  console.log("Main JS asset exists");
106
}
107
```
108

109
## Removing Assets
110

111
### delete() Method
112

113
Removes an asset from the manifest:
114

115
```typescript { .api }
116
delete(key: AssetsStorageKey): boolean;
117
```
118

119
```typescript
120
// Remove specific asset
121
const removed = manifest.delete("old-file.js");
122
console.log(`Asset removed: ${removed}`);
123
```
124

125
### clear() Method
126

127
Removes all assets from the manifest:
128

129
```typescript { .api }
130
clear(): void;
131
```
132

133
```typescript
134
// Clear all assets (useful in watch mode)
135
manifest.clear();
136
```
137

138
## Asset Processing Utilities
139

140
### fixKey() Method
141

142
Normalizes asset keys by replacing backslashes with forward slashes:
143

144
```typescript { .api }
145
fixKey(key: AssetsStorageKey): AssetsStorageKey;
146
```
147

148
```typescript
149
const normalized = manifest.fixKey("assets\\images\\logo.png");
150
// Result: "assets/images/logo.png"
151
```
152

153
### getExtension() Method
154

155
Extracts file extension using the configured regex:
156

157
```typescript { .api }
158
getExtension(filename: string): string;
159
```
160

161
```typescript
162
const ext = manifest.getExtension("main.js.map");
163
// Result: ".js.map"
164

165
const ext2 = manifest.getExtension("archive.tar.gz");
166
// Result: ".tar.gz"
167
```
168

169
### getPublicPath() Method
170

171
Resolves the public path for a filename:
172

173
```typescript { .api }
174
getPublicPath(filename: string): string;
175
```
176

177
```typescript
178
// With string publicPath
179
manifest.options.publicPath = "https://cdn.example.com/";
180
const url = manifest.getPublicPath("main.js");
181
// Result: "https://cdn.example.com/main.js"
182

183
// With function publicPath
184
manifest.options.publicPath = (filename, manifest) => {
185
  return `https://cdn-${process.env.NODE_ENV}.com/${filename}`;
186
};
187
```
188

189
## File Operations
190

191
### getOutputPath() Method
192

193
Gets the absolute path where the manifest will be written:
194

195
```typescript { .api }
196
getOutputPath(): string;
197
```
198

199
```typescript
200
const outputPath = manifest.getOutputPath();
201
console.log(`Manifest will be written to: ${outputPath}`);
202
```
203

204
### writeTo() Method
205

206
Writes the manifest to a specific file path:
207

208
```typescript { .api }
209
writeTo(destination: string): Promise<void>;
210
```
211

212
```typescript
213
// Write to custom location
214
await manifest.writeTo("/custom/path/manifest.json");
215
```
216

217
## Serialization
218

219
### toJSON() Method
220

221
Gets the manifest data for JSON serialization (runs transform hook):
222

223
```typescript { .api }
224
toJSON(): AssetsStorage;
225
```
226

227
```typescript
228
const data = manifest.toJSON();
229
console.log(JSON.stringify(data, null, 2));
230
```
231

232
### toString() Method
233

234
Converts the manifest to a JSON string:
235

236
```typescript { .api }
237
toString(): string;
238
```
239

240
```typescript
241
const jsonString = manifest.toString();
242
console.log(jsonString);
243
```
244

245
## Proxy Interface
246

247
### getProxy() Method
248

249
Returns a proxy that allows bracket notation access:
250

251
```typescript { .api }
252
getProxy(raw?: boolean): this & { [key: AssetsStorageKey]: AssetsStorageValue };
253
```
254

255
```typescript
256
const proxy = manifest.getProxy();
257

258
// Use bracket notation
259
proxy["main.js"] = "main-abc123.js";
260
console.log(proxy["main.js"]);
261

262
// Check existence
263
if ("main.js" in proxy) {
264
  console.log("Asset exists");
265
}
266

267
// Delete with delete operator
268
delete proxy["old-file.js"];
269
```
270

271
## Additional Public Methods
272

273
### processAssetsByChunkName() Method
274

275
Processes webpack assets by chunk name:
276

277
```typescript { .api }
278
processAssetsByChunkName(assets: StatsCompilation['assetsByChunkName'], hmrFiles: Set<string>): void;
279
```
280

281
```typescript
282
// Internal usage by the plugin - processes webpack asset chunks
283
const stats = compilation.getStats().toJson();
284
const hmrFiles = new Set<string>();
285
manifest.processAssetsByChunkName(stats.assetsByChunkName, hmrFiles);
286
```
287

288
### shouldWriteToDisk() Method
289

290
Determines if the manifest should be written to disk using the file system:
291

292
```typescript { .api }
293
shouldWriteToDisk(compilation: Compilation): boolean;
294
```
295

296
```typescript
297
// Check if manifest should be written to disk
298
const shouldWrite = manifest.shouldWriteToDisk(compilation);
299
if (shouldWrite) {
300
  await manifest.writeTo(outputPath);
301
}
302
```
303

304
### inDevServer() Method
305

306
Detects if the plugin is running in webpack-dev-server:
307

308
```typescript { .api }
309
inDevServer(): boolean;
310
```
311

312
```typescript
313
// Check if running in development server
314
if (manifest.inDevServer()) {
315
  console.log("Running in webpack-dev-server");
316
  // Different behavior for dev server
317
}
318
```
319

320
## Usage Examples
321

322
### Basic Asset Management
323

324
```typescript
325
import { WebpackAssetsManifest } from "webpack-assets-manifest";
326

327
const manifest = new WebpackAssetsManifest();
328

329
// Add assets
330
manifest.set("main.js", "main-abc123.js");
331
manifest.set("styles.css", "styles-def456.css");
332

333
// Check and retrieve
334
if (manifest.has("main.js")) {
335
  const mainJs = manifest.get("main.js");
336
  console.log(`Main JS: ${mainJs}`);
337
}
338

339
// List all assets
340
console.log(manifest.toString());
341
```
342

343
### Custom Asset Processing
344

345
```typescript
346
const manifest = new WebpackAssetsManifest({
347
  customize(entry, original, manifest, asset) {
348
    if (entry && typeof entry.value === "string") {
349
      // Add integrity if available
350
      const integrity = asset?.info[manifest.options.integrityPropertyName];
351
      if (integrity) {
352
        return {
353
          key: entry.key,
354
          value: {
355
            src: entry.value,
356
            integrity,
357
          },
358
        };
359
      }
360
    }
361
    return entry;
362
  },
363
});
364
```
365

366
### Programmatic Manifest Building
367

368
```typescript
369
const manifest = new WebpackAssetsManifest();
370

371
// Build manifest programmatically
372
const assets = [
373
  { key: "main.js", value: "main-abc123.js" },
374
  { key: "vendor.js", value: "vendor-def456.js" },
375
  { key: "styles.css", value: "styles-ghi789.css" },
376
];
377

378
assets.forEach(({ key, value }) => {
379
  manifest.set(key, value);
380
});
381

382
// Write to custom location
383
await manifest.writeTo("./build/asset-manifest.json");
384
```