AssetGraph: treating a web page as a dependency graph you can rewrite

The observation that most build tasks are graph problems

The stated motivation is unusually well put. All web build tools, even those targeting very specific problems, have to get a bunch of boring stuff right just to get started, such as loading files from disc, parsing and serializing them, charsets, inlining, finding references to other files, and the resolution and updating of urls. The observation that inspired the project is that most of these tasks can be viewed as graph problems, where the nodes are the assets, meaning HTML, CSS, images and JavaScript, and the edges are the relations between them, for example anchor tags, image tags, favourite icons and CSS background-image properties. That reframing is what makes the framework extensible. Instead of a fixed pipeline of transformations, you get a data model you can query, and the tools on top of it are written as queries and mutations against that model. The library description calls it an auto discovery dependency graph based optimization framework for web pages and applications, and the auto discovery part comes from the ability to find assets based on your declarative code, which the documentation says reduces the configuration needs to a minimum.

Change one url and every reference follows

The consequence of the graph model is stated in a single sentence that is worth repeating because it is the property that makes the library worth learning. An AssetGraph object is a collection of assets, which are the nodes, and the relations between them, which are the edges, and it is a basic data model that allows you to populate, query and manipulate the graph at a high level of abstraction. The example given is that if you change the url of an asset, all relations pointing at it are automatically updated. That is a guarantee rather than a feature you implement, and it is the reason a hand-rolled build script ends up with a hundred special cases. Individual assets can also be inspected and massaged using a relevant API, with jsdom for HTML, PostCSS for CSS and an Esprima AST for JavaScript, which means the graph does not force you to work with raw text when you need to change one attribute. The features list follows from this: finding explicit dependencies between JavaScript and CSS and rolling them out as script and link tags, bundling and inlining CSS and JavaScript, creating a cache manifest with references to all the assets the app needs to work offline, moving assets to a static directory and renaming them to md5.extension so the server can be configured with a far-future Cache-Control, and rewriting references to get static assets onto a CDN.

Inline assets are first class, which removes a lot of special cases

The design decision that saves the most work in practice is that inline assets are represented the same way as non-inline ones, so inline scripts, stylesheets and images specified as data: urls are also first class nodes in the graph. The stated benefit is that you do not need to dig into the HTML of the containing asset to manipulate them. The extreme example in the documentation is an HTML asset with a conditional comment containing an inline stylesheet with an inline image, which is modelled as four separate assets. The example that demonstrates it:

<!DOCTYPE html>
<html>
  <head>
    <!--[if !IE]> -->
    <style type="text/css">
      body {
        background-image: url(data:image/gif;base64,R0lGODlhAQABAID/AMDAwAAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw==);
      }
    </style>
    <!-- <![endif]-->
  </head>
  <body></body>
</html>

This is the kind of thing that a regular expression based approach gets wrong, and it is why the framework tracks relations per file type. The supported list is long. For HTML there are anchor, link with a stylesheet or shortcut icon or fluid icon or alternate or serviceworker relation, script, style, the html manifest attribute, img, video, audio, applet, embed, esi include, iframe, svg and the Open Graph meta property. SVG covers style elements, inline style attributes, event handlers, the xml-stylesheet processing instruction and font-face-src. CSS covers sourceMappingURL comments, background-image urls, import urls, behavior urls, the AlphaImageLoader filter and the src of a font-face rule. JavaScript covers sourceMappingURL comments and a homegrown string-to-url syntax for referencing external files. Web manifests cover icon urls, related_applications and start_url, and cache manifests cover the entries in the CACHE, NETWORK and FALLBACK sections.

Querying with MongoDB-like syntax over the sift module

Once the graph is populated you need to find things in it, and the query interface is the part of the API you will type most. AssetGraph supports a flexible syntax for finding assets and relations in a populated graph using the findAssets and findRelations methods, both of which take a query object as the first argument. The query engine uses MongoDB-like queries via the sift module, and the documentation points you at that module for the advanced features. The simplest call takes no query at all and returns every asset in the graph:

var allAssets = assetGraph.findAssets();

Finding assets by type follows the same shape, with a type field in the query object. The dependency on sift is a deliberate one and it has a practical effect: you can learn the query syntax from MongoDB documentation you have already seen, and the full filter set is available rather than a hand-rolled subset. It also means a query that looks reasonable in MongoDB terms may behave differently here, since sift implements the subset that makes sense over plain objects. The sift module is pinned in the dependency list at version 7.0.1, and the esquery dependency is an interesting one to note, since it comes from a GitHub URL rather than the registry, which tells you the project has taken a fork of a query library for JavaScript ASTs.

The framework has a family of tools built on top of it

The list of tools built with AssetGraph is the best evidence of what the framework is actually good at, because each one is a different shape of problem solved with the same graph. assetgraph-builder is described as a static web page build system that post-processes your website with extremely little configuration, and it is the prepackaged build system the documentation points to if you do not want to write your own. subfont is a tool for webfont loading that applies best practice loading techniques and generates optimal font subsets. hyperlink is a link checker that ensures internal and external links are intact and up to date. seespee is a Content-Security-Policy generator that tells you the minimum policy a given page needs, which is a genuinely hard problem and one that the graph model makes tractable because the assets are already enumerated. trackingdog is a command line tool that finds the original source location of a line and column in a generated file using the source map. bringhome downloads a web page and its assets to a local directory. There is also a separate assetgraph-sprite transform that optimises CSS background images by creating sprite images, guided by custom CSS properties with an -ag-sprite prefix, and the features list notes that Graphviz can be used to visualise dependencies at any step, which is a debugging aid worth having when a build pipeline goes wrong.

A pre-release package version against a six-year-old release list

The maintenance signals here need care. The package version in the metadata is 7.0.0-pre, which is a pre-release identifier, while the published release list shows v6.1.2 from 2020-08-02 with the note about a cyclic graph warning when renaming, then v5.11.0 from 2019 and v5.3.0 from 2018 which added the HTTP Referer header. So the tagged releases stopped in 2020 while the package version has moved to a 7.0.0 pre-release state, and the last push was on 2026-10-16. That combination reads as a project that is still worked on but whose releases are not the mechanism by which people get the code, which for an npm package normally means installing from a branch or a fork. The repository layout shows the work in progress, with a lib directory for the implementation, a test directory, a testdata directory for fixtures, a netlify.toml, an appveyor.yml for Windows continuous integration, a .mocharc.yml for the test runner, a .eslintrc and a .prettierrc for the JavaScript style, and a jsdoc.json for the API documentation. The licence field on the repository says BSD-3-Clause, and the dependency list is long, with jsdom, postcss, terser, html-minifier and cssnano in it, which is the price of treating every file type as first class.

Editorial conclusion

AssetGraph is a good fit for a team building its own site tooling, that needs to reason about a page as a graph rather than as a tree of files, and that wants to rewrite references across HTML, CSS, JavaScript and SVG in one pass. It is the wrong tool for a project that just wants a bundler, since a prepackaged build system exists separately for that, and it is the wrong tool if you will not maintain your own pipeline, because AssetGraph is a framework rather than a product. Before adopting it, read the asset and relation type list, because the coverage of each file type determines how much of your site you can express in the graph, and check the query syntax documentation since the MongoDB-like queries come from an external module. The package is BSD-3-Clause licensed, the last push was on 2026-10-16, and the package version is 7.0.0-pre.

Frequently asked questions

Official sources

1. assetgraph/assetgraph on GitHub
2. Issues
3. License: BSD-3-Clause
4. README
5. Releases