tessl/npm-webpack-assets-manifest

Webpack plugin that generates JSON manifest files mapping original filenames to their hashed versions with extensive customization options

—

Pending

Overview

Eval results

Files

Asset Management

Name: tessl/npm-webpack-assets-manifest
Author: tessl

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

Asset Storage Interface

class WebpackAssetsManifest {
  // Asset storage
  assets: AssetsStorage;
  assetNames: Map<string, string>;
  
  // Core methods
  set(key: AssetsStorageKey, value: AssetsStorageValue): this;
  setRaw(key: AssetsStorageKey, value: AssetsStorageValue): this;
  get(key: AssetsStorageKey, defaultValue?: AssetsStorageValue): AssetsStorageValue | undefined;
  has(key: AssetsStorageKey): boolean;
  delete(key: AssetsStorageKey): boolean;
  clear(): void;
  
  // Utility methods
  fixKey(key: AssetsStorageKey): AssetsStorageKey;
  getExtension(filename: string): string;
  getPublicPath(filename: string): string;
  getOutputPath(): string;
  
  // Serialization methods
  toJSON(): AssetsStorage;
  toString(): string;
  
  // File operations
  writeTo(destination: string): Promise<void>;
  
  // Additional public methods
  processAssetsByChunkName(assets: StatsCompilation['assetsByChunkName'], hmrFiles: Set<string>): void;
  shouldWriteToDisk(compilation: Compilation): boolean;
  inDevServer(): boolean;
  
  // Proxy interface
  getProxy(raw?: boolean): this & { [key: AssetsStorageKey]: AssetsStorageValue };
}

Adding Assets

set() Method

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

set(key: AssetsStorageKey, value: AssetsStorageValue): this;

// Add a simple asset mapping
manifest.set("main.js", "main-abc123.js");

// Add with complex value (when integrity is enabled)
manifest.set("styles.css", {
  src: "styles-def456.css",
  integrity: "sha256-xyz789...",
});

setRaw() Method

Adds an asset without processing through hooks:

setRaw(key: AssetsStorageKey, value: AssetsStorageValue): this;

// Bypass all processing
manifest.setRaw("vendor.js", "vendor-ghi789.js");

Retrieving Assets

get() Method

Retrieves an asset value with optional default:

get(key: AssetsStorageKey, defaultValue?: AssetsStorageValue): AssetsStorageValue | undefined;

// Get asset value
const mainJs = manifest.get("main.js");

// Get with default value
const fallback = manifest.get("missing.js", "default.js");

has() Method

Checks if an asset exists in the manifest:

has(key: AssetsStorageKey): boolean;

if (manifest.has("main.js")) {
  console.log("Main JS asset exists");
}

Removing Assets

delete() Method

Removes an asset from the manifest:

delete(key: AssetsStorageKey): boolean;

// Remove specific asset
const removed = manifest.delete("old-file.js");
console.log(`Asset removed: ${removed}`);

clear() Method

Removes all assets from the manifest:

clear(): void;

// Clear all assets (useful in watch mode)
manifest.clear();

Asset Processing Utilities

fixKey() Method

Normalizes asset keys by replacing backslashes with forward slashes:

fixKey(key: AssetsStorageKey): AssetsStorageKey;

const normalized = manifest.fixKey("assets\\images\\logo.png");
// Result: "assets/images/logo.png"

getExtension() Method

Extracts file extension using the configured regex:

getExtension(filename: string): string;

const ext = manifest.getExtension("main.js.map");
// Result: ".js.map"

const ext2 = manifest.getExtension("archive.tar.gz");
// Result: ".tar.gz"

getPublicPath() Method

Resolves the public path for a filename:

getPublicPath(filename: string): string;

// With string publicPath
manifest.options.publicPath = "https://cdn.example.com/";
const url = manifest.getPublicPath("main.js");
// Result: "https://cdn.example.com/main.js"

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

File Operations

getOutputPath() Method

Gets the absolute path where the manifest will be written:

getOutputPath(): string;

const outputPath = manifest.getOutputPath();
console.log(`Manifest will be written to: ${outputPath}`);

writeTo() Method

Writes the manifest to a specific file path:

writeTo(destination: string): Promise<void>;

// Write to custom location
await manifest.writeTo("/custom/path/manifest.json");

Serialization

toJSON() Method

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

toJSON(): AssetsStorage;

const data = manifest.toJSON();
console.log(JSON.stringify(data, null, 2));

toString() Method

Converts the manifest to a JSON string:

toString(): string;

const jsonString = manifest.toString();
console.log(jsonString);

Proxy Interface

getProxy() Method

Returns a proxy that allows bracket notation access:

getProxy(raw?: boolean): this & { [key: AssetsStorageKey]: AssetsStorageValue };

const proxy = manifest.getProxy();

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

// Check existence
if ("main.js" in proxy) {
  console.log("Asset exists");
}

// Delete with delete operator
delete proxy["old-file.js"];

Additional Public Methods

processAssetsByChunkName() Method

Processes webpack assets by chunk name:

processAssetsByChunkName(assets: StatsCompilation['assetsByChunkName'], hmrFiles: Set<string>): void;

// Internal usage by the plugin - processes webpack asset chunks
const stats = compilation.getStats().toJson();
const hmrFiles = new Set<string>();
manifest.processAssetsByChunkName(stats.assetsByChunkName, hmrFiles);

shouldWriteToDisk() Method

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

shouldWriteToDisk(compilation: Compilation): boolean;

// Check if manifest should be written to disk
const shouldWrite = manifest.shouldWriteToDisk(compilation);
if (shouldWrite) {
  await manifest.writeTo(outputPath);
}

inDevServer() Method

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

inDevServer(): boolean;

// Check if running in development server
if (manifest.inDevServer()) {
  console.log("Running in webpack-dev-server");
  // Different behavior for dev server
}

Usage Examples

Basic Asset Management

import { WebpackAssetsManifest } from "webpack-assets-manifest";

const manifest = new WebpackAssetsManifest();

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

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

// List all assets
console.log(manifest.toString());

Custom Asset Processing

const manifest = new WebpackAssetsManifest({
  customize(entry, original, manifest, asset) {
    if (entry && typeof entry.value === "string") {
      // Add integrity if available
      const integrity = asset?.info[manifest.options.integrityPropertyName];
      if (integrity) {
        return {
          key: entry.key,
          value: {
            src: entry.value,
            integrity,
          },
        };
      }
    }
    return entry;
  },
});

Programmatic Manifest Building

const manifest = new WebpackAssetsManifest();

// Build manifest programmatically
const assets = [
  { key: "main.js", value: "main-abc123.js" },
  { key: "vendor.js", value: "vendor-def456.js" },
  { key: "styles.css", value: "styles-ghi789.css" },
];

assets.forEach(({ key, value }) => {
  manifest.set(key, value);
});

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

Install with Tessl CLI

npx tessl i tessl/npm-webpack-assets-manifest

docs

asset-management.md

hooks.md

index.md

plugin-configuration.md

utilities.md

tile.json

tessl/npm-webpack-assets-manifest