AssetGraph-builder: Web Application Build System

9.3.0 · active · verified Tue Apr 21

AssetGraph-builder is a robust, opinionated build system primarily designed for single-page web applications, leveraging the powerful AssetGraph library. It distinguishes itself by requiring no explicit build manifest; instead, it intelligently discovers all project assets (HTML, CSS, JavaScript, images, fonts, etc.) by traversing the dependency graph from specified HTML entry points. The current stable version is 9.3.0. While no fixed release cadence is stated, the project demonstrates active maintenance with recent updates, with the latest release in December 2023. Key features include bundling, minification (JavaScript with Terser, CSS with cssnano, HTML with html-minifier), advanced image optimization (supporting various tools like Sharp, pngquant, jpegtran), cache busting via MD5-hashed filenames, CDN rewriting, and automatic Content-Security-Policy updates. It excels in optimizing web assets for production, reducing HTTP requests, and improving load times, making it suitable for complex static site and web application deployments without extensive configuration.

Common errors

```
Error: spawn pngquant ENOENT
```
cause One or more of the optional image optimization CLI tools (like `pngquant`, `optipng`, `jpegtran`) are not installed or not available in the system's PATH.

fix Install the missing command-line tools on your operating system. For example, on Ubuntu/Debian: `sudo apt-get install pngquant optipng jpegtran`. For macOS using Homebrew: `brew install pngquant optipng libjpeg`.
```
Error: Input file 'path/to/your/index.html' not found
```
cause The specified input HTML file does not exist at the given path, or the path is incorrect.

fix Verify the absolute or relative path to your primary HTML entry file. Ensure the command is executed from a directory where the relative path is correct, or provide the full absolute path.
```
Cannot find module 'assetgraph'
```
cause The `assetgraph` package, a peer dependency, is not installed or resolvable in the environment where `assetgraph-builder` is run.

fix Ensure `assetgraph` is installed alongside `assetgraph-builder`. If using npm, `npm install assetgraph` in your project directory. If `assetgraph-builder` is installed globally, you might need to ensure global peer dependencies are met or install `assetgraph` locally in projects where you run the builder.

Warnings

gotcha Full image optimization features require external system-level libraries (e.g., pngquant, GraphicsMagick, OptiPNG, JpegTran). While `assetgraph-builder` provides npm wrappers for some (e.g., `pngquant-bin`), others like `GraphicsMagick` require manual installation on the host system to unlock their capabilities, as indicated in the README.
Fix: Consult the 'Installation' section of the README for instructions on installing required external system libraries for full functionality, typically via a package manager like `apt` on Linux or `brew` on macOS.
gotcha AssetGraph-builder operates without a build manifest, automatically discovering assets by traversing the DOM. This can be a paradigm shift for developers used to explicit configuration files (e.g., Webpack, Grunt). Unexpected assets might be included or excluded if the initial HTML entry point doesn't fully represent the application's true dependency graph.
Fix: Ensure your primary HTML entry files accurately reference all critical assets. For complex scenarios, understand AssetGraph's underlying traversal logic and its extensibility to fine-tune asset discovery and processing.
breaking The package performs cache busting by renaming JavaScript, CSS, and image files with an MD5 hash prefix. This process fundamentally changes asset filenames, which can break existing build pipelines, caching strategies, or CDN configurations that rely on static file paths or more predictable naming conventions.
Fix: Configure your deployment and CDN solutions to handle dynamically generated, hashed filenames. This typically involves serving assets from a dedicated folder with far-future expiry headers and ensuring that your HTML references the new hashed names correctly.
gotcha AssetGraph-builder automatically updates existing Content-Security-Policy (CSP) meta tags in HTML to reflect changes made during the build, including adding hashes for inline scripts and stylesheets. While a helpful feature, this can inadvertently relax strict CSPs or conflict with server-side CSP headers if not carefully managed, potentially introducing security vulnerabilities or unexpected content blocking.
Fix: Thoroughly review the generated CSP after a build. Test your application in various environments to ensure the updated CSP is still secure and functional. If server-side CSPs are in use, ensure they are compatible with the client-side meta tag modifications or disable automatic CSP updates if finer control is needed.

Install

npm install assetgraph-builder npm
yarn add assetgraph-builder yarn
pnpm add assetgraph-builder pnpm

Imports

buildProduction
wrong:
```
import { buildProduction } from 'assetgraph-builder';
```
correct:
```
npm install -g assetgraph-builder
```
AssetGraph-builder is primarily a command-line interface (CLI) tool. The `buildProduction` command is globally installed for direct terminal execution, not intended for programmatic import as a library.

Quickstart

Installs the global CLI tool and builds a production-ready website from an HTML entry point, optimizing assets to a specified output directory.

npm install -g assetgraph-builder
buildProduction path/to/your/index.html -o path/to/output/directory

view raw JSON →