Brunch: the deprecated build tool, and how to use it safely

The problem Brunch solves, and the deprecation that now surrounds it

Brunch targets front-end projects that want a build step without a long configuration file. The README describes it as a "fast front-end web app build tool with simple declarative config and seamless incremental compilation for rapid development". The intended user is someone building a browser application out of JavaScript, CSS and templates who does not want to wire up a general-purpose task runner. Brunch compiles, concatenates and minifies those inputs, and it watches them so a save triggers a partial rebuild rather than a full one.

The repository is not archived, and the last push was on 2026-04-19. The README, however, carries a deprecation notice stating that the npm package "is deprecated and has been transferred to a new owner". The original maintainer writes that future versions "will be published by a different author for a completely unrelated purpose" and that the package "will not receive any further updates from the original author". That is the central fact about Brunch today. The code in the repository and the tarball at version 4.0.2 are still installable, but the name on npm no longer points at the same maintainer's work, and the README tells readers to pin rather than update.

How the pipeline works: config, watcher and incremental rebuild

Brunch's model is a pipeline of plugins over a directory tree. Source files live in app/, compiled output goes to public/, and brunch-config describes the mapping. Plugins are attached per file extension, so a .js file passes through the JavaScript compiler, a .css file through the CSS compiler, and so on. The repository layout reflects this: lib/ holds the core, packages/ holds related packages, and bin/brunch is the executable declared in package.json.

Incremental compilation is the part that matters for daily work. The dependency list includes chokidar for file watching and fcache for caching, so a watch session rebuilds only the files whose inputs changed. The package.json description calls this "core support for source maps", which means the compiled output can point back at the original sources in a browser's developer tools.

Dependency handling is delegated rather than reimplemented. The dependency list names deppack and deps-install, which resolve and install npm packages referenced from application code. That is a deliberate split: Brunch itself stays small, and dependency resolution is a separate concern. The trade-off is that the resolution behaviour you get depends on those packages, not on Brunch alone.

Installing Brunch and running a first build

The README's install path is a global npm install, and it lists 4.0.2 among the versions considered safe. Pin that version rather than installing the bare package name.

npm install -g [email protected]

After that, create a project from a skeleton. The README gives the command as brunch new with an optional --skeleton url, and notes that the default skeleton (dead-simple) "doesn't have any opinions about frameworks or libraries". The skeletons page is described as containing over 50 boilerplate projects.

brunch new

For development, the README's command is watch with the server flag. It tells Brunch to watch the project and incrementally rebuild it when source files change, and the flag launches a simple web server with push state support.

brunch watch --server

For a distribution build, the README uses build with the production flag, which by default enables minification.

brunch build --production

To see whether the package is present in a project at all, the README's first remediation step is npm ls brunch, and its debug flag is -d, passed to any command.

npm ls brunch
brunch build -d

If you install from a tarball rather than the registry, the README publishes sha256 checksums for the safe versions, including af179ebc33d22e7b5af4b61e498ad0e8f5f6edcf3190aea0ed33d19d26b9286e for brunch-4.0.2.tgz. Comparing the checksum of your download against that value is the one integrity check the project documents.

The deprecation is the limitation, and pinning is the workaround

The most concrete failure mode is not a bug in the compiler. It is the supply chain. Because ownership moved and the README states that future versions come from a different author for an unrelated purpose, a routine npm update or npm install can pull in code the original maintainers never reviewed. The README is explicit: readers "should not assume future versions are safe to upgrade to without review".

The README's own remediation is to pin the dependency in package.json:

"brunch": "4.0.2"

That fixes the version but not the maintenance gap. There will be no further updates from the original author, so a security fix in a transitive dependency has to be handled by you, not by upstream. Brunch is also the wrong tool if your project needs native ES module output as a first-class target, or if you depend on plugins that track a faster-moving ecosystem. The README does not document rollback, migration or an upgrade path off Brunch, so anyone leaving has to plan that themselves. Treat the tool as frozen rather than evolving.

Alternatives, and where the approach actually differs

Webpack is the obvious comparison, and the difference is in the configuration model rather than in features. Brunch keeps configuration declarative: you describe which extensions map to which plugins and let the pipeline run. Webpack is built around a module graph and a loader and plugin system, and its configuration expresses that graph. For a small application with a handful of file types, Brunch's config is shorter and the mental model is a directory transform. For an application with code splitting, dynamic imports and a large loader chain, Webpack's model is the one that fits, and Brunch's simplicity stops being an advantage.

Gulp is a different kind of alternative. It is a task runner, so the build is a sequence of streams you write yourself. Brunch ships an opinionated pipeline and a watcher; Gulp ships primitives and leaves the pipeline to you. Choosing between them is choosing between a fixed convention and full control over each step.

The practical point is that both alternatives are actively released. Brunch's own package.json lists webpack, grunt, gulp and vue among its keywords, which acknowledges the neighbourhood it sits in. Given the deprecation notice, a new project has little reason to start on Brunch rather than on one of those.

Licence and the cost of keeping Brunch in a tree

Brunch is MIT licensed. The LICENSE file is at the repository root, and the copyright line names Paul Miller, Elan Shanker, Nik Graf, Thomas Schranz, Allan Berger, Jan Monschke and Martin Schürrer, with 2021 as the year. MIT is permissive, so using, modifying and redistributing the code is allowed provided the licence and copyright notice are preserved. Nothing in the licence prevents you from vendoring version 4.0.2 or from maintaining a fork. This is not legal advice; check how your organisation handles third-party notices.

The ongoing cost is different from the licence cost. Because the package name changed hands, every dependency audit has to distinguish the version you pinned from whatever the registry now serves under the same name. That means an explicit pin, a lockfile entry, and a checksum check at install time if you fetch tarballs. The engine requirement in package.json is Node >= 12.13, so runtimes older than that are out of scope. Upgrading Brunch itself is not a maintenance activity you can plan for, because the README states there will be no further updates from the original author. The realistic upgrade path is replacement, not a new version.

Editorial conclusion

Brunch still fits small front-end projects whose maintainers are willing to pin brunch 4.0.2 and accept an unmaintained dependency. It does not fit teams that need a supported toolchain, native ES module output or a plugin ecosystem with current releases. Before adopting it, run npm ls brunch to see whether the package is already in your tree, and verify the sha256 checksum of the tarball you install against the value in the README.

Frequently asked questions

Official sources

1. brunch/brunch on GitHub
2. License: MIT
3. Project website
4. README
5. Releases