{"id":15518,"library":"assetgraph-builder","title":"AssetGraph-builder: Web Application Build System","description":"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.","status":"active","version":"9.3.0","language":"javascript","source_language":"en","source_url":"git://github.com/assetgraph/assetgraph-builder","tags":["javascript","assetgraph","web","build","build system","single page","web application","static html","cache manifest"],"install":[{"cmd":"npm install assetgraph-builder","lang":"bash","label":"npm"},{"cmd":"yarn add assetgraph-builder","lang":"bash","label":"yarn"},{"cmd":"pnpm add assetgraph-builder","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core graph traversal and manipulation library. Also a peer dependency.","package":"assetgraph","optional":false},{"reason":"High-performance image processing library.","package":"sharp","optional":false},{"reason":"Npm wrapper for pngquant CLI tool for PNG optimization.","package":"pngquant-bin","optional":false},{"reason":"Npm wrapper for jpegtran CLI tool for JPEG optimization.","package":"jpegtran-bin","optional":false},{"reason":"JavaScript minification.","package":"terser","optional":false},{"reason":"CSS minification.","package":"cssnano","optional":false},{"reason":"HTML minification.","package":"html-minifier","optional":false},{"reason":"Optional dependency for GraphicsMagick integration, enabling more advanced image manipulation features.","package":"gm","optional":true}],"imports":[{"note":"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.","wrong":"import { buildProduction } from 'assetgraph-builder';","symbol":"buildProduction","correct":"npm install -g assetgraph-builder"}],"quickstart":{"code":"npm install -g assetgraph-builder\nbuildProduction path/to/your/index.html -o path/to/output/directory","lang":"javascript","description":"Installs the global CLI tool and builds a production-ready website from an HTML entry point, optimizing assets to a specified output directory."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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`.","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.","error":"Error: spawn pngquant ENOENT"},{"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.","cause":"The specified input HTML file does not exist at the given path, or the path is incorrect.","error":"Error: Input file 'path/to/your/index.html' not found"},{"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.","cause":"The `assetgraph` package, a peer dependency, is not installed or resolvable in the environment where `assetgraph-builder` is run.","error":"Cannot find module 'assetgraph'"}],"ecosystem":"npm"}