Build Awesome (Eleventy) review: a simpler static site generator for JavaScript teams

The problem Build Awesome solves, and who it is actually for

Most site generators make you pick a template language before you pick a site. Build Awesome goes the other way. The README describes it as "a simpler static site generator" and "an alternative to Jekyll" that "transforms a directory of templates (of varying types) into HTML". That phrase, of varying types, is the whole pitch. A single project can hold an HTML page, a Markdown post, a JavaScript template and a Nunjucks partial, and the generator walks the directory and produces HTML from all of them.

The audience follows from that. It suits teams that already write JavaScript and want to keep their build in the Node ecosystem rather than adopt a Ruby toolchain, which is the Jekyll comparison the README itself draws. It suits people migrating a blog or documentation site where the content is mostly Markdown but a few pages need real logic. It is a poor fit for anyone who wants a component framework to own routing and state; Build Awesome emits files, it does not run an application.

The README lists the supported inputs plainly: HTML, Markdown, JavaScript, Liquid and Nunjucks, "with addons for WebC, Sass, Vue, Svelte, TypeScript, JSX, and many others". Note the word addons. The core set is the first five; the rest arrive through the plugin system documented at 11ty.dev/docs/plugins/.

How the template directory becomes HTML

The architecture visible in the repository is a Node package with a CLI. package.json declares "main": "./src/Core.js", so the programmatic entry point is a Core module, and the bin field maps the command name eleventy to cmd.cjs at the repository root. That is the shape of the data flow: cmd.cjs is the command-line front door, src/Core.js is the library that does the work, and the input is a directory of templates rather than a set of routes you register in code.

The package is published as an ES module. package.json sets "type": "module", and the exports map gives two entries for the root: an import condition pointing at ./src/Core.js and a require condition pointing at ./src/RequireEsmFeatureTest.cjs. That second file is named for a feature test, which tells you the maintainers are gating CommonJS consumers behind a capability check rather than promising full parity. If your build is CommonJS, that is the seam to watch.

There is also a documented subpath export, "./utils/git": "./src/Util/Git.js", so Git utilities are reachable as a supported import rather than an internal file. A UserConfig type export exists for TypeScript users, generated by the typescript script (tsc plus scripts/prune-types.js). The repository is a workspace monorepo: the workspaces array lists packages/browser and packages/build-awesome, and the test script fans out to a server suite and a browser suite, with the browser tests running in Vitest Browser Mode.

Installing Build Awesome and running a first build

The README gives the install command directly. Run it in your project root, and note that the package is a development dependency, not a runtime one, because the output is static HTML.

npm install @awesome.me/buildawesome --save-dev

# Backwards compatible here too:
npm install @11ty/eleventy --save-dev

Both lines are quoted from the README, which labels the second one "Backwards compatible here too". The npm package name in package.json is still @11ty/eleventy at version 4.0.0-alpha.10, so the two names are not a typo; they are two doors into the same tool. Pick one and stay consistent, because installing both would leave two entries in your devDependencies for one generator.

Before any of that, check the engine constraint. package.json sets "engines": { "node": ">=22.15" }, so an older Node release will not satisfy the declared requirement.

"engines": {
  "node": ">=22.15"
}

The bin field registers the command name eleventy, pointing at cmd.cjs, so once the package is installed the CLI is available through your package manager's script runner. The README does not print a sample npm script, so the honest next step is the Getting Started guide it links: https://www.11ty.dev/docs/getting-started/. That page, not the README, is where the first-run walkthrough lives.

Where Build Awesome gets in your way

The most concrete limitation is the version number. package.json on the default branch declares 4.0.0-alpha.10, and the three most recent releases listed are v4.0.0-alpha.8, v4.0.0-alpha.9 and v4.0.0-alpha.10. There is no stable 4.x in that list. A team that needs a frozen, tagged, non-alpha dependency has to look at the 3.x line, which this material does not describe, or wait. That is not a criticism of the code; it is a statement about what the release list contains.

The second constraint is Node. The engines field demands 22.15 or newer. On a machine pinned to an older LTS, the install may succeed and the run may not, and the README offers no troubleshooting path for that case.

The third is the CommonJS boundary. The exports map routes require() to src/RequireEsmFeatureTest.cjs, a file whose name announces that it tests for an ES module feature before proceeding. If your toolchain is CommonJS and you are not on a Node release that passes that test, this is where you will find out.

Finally, addons are not core. The README lists WebC, Sass, Vue, Svelte, TypeScript and JSX as addons, and points to the plugins documentation. If your site depends on one of those, your build has a dependency the core install does not cover, and the README does not enumerate which plugin provides which.

Build Awesome against Jekyll, and against a JavaScript framework

The README names its own alternative: "An alternative to Jekyll. Written in JavaScript." The real difference is the runtime you have to keep on the machine. Jekyll is a Ruby program, so a Jekyll site carries a Ruby toolchain and the gem ecosystem with it. Build Awesome is a Node package installed through npm, which is what the installation block shows. For a team whose CI image and local setup are already Node, that removes one language from the build. It does not remove the build step; both tools still compile a directory of templates into HTML ahead of time.

The other comparison worth drawing is against JavaScript frameworks that render components. The README lists Vue and Svelte, but as addons, not as the core model. Build Awesome's core model is a directory of templates of varying types that becomes HTML. A framework's core model is a component tree with a router. If your pages are documents, the directory model is less machinery. If your pages are views over changing client state, the directory model is the wrong shape and no addon changes that.

On testing, the repository is unusually explicit. It runs ava as the primary suite in test/, the Node.js test runner as a secondary suite in test_node/, and Vitest in Browser Mode for packages/browser/test/. A separate repository, 11ty/buildbenchmark, exists for performance regressions. That is a real signal about how the project is maintained, and it is more informative than any count of stars or issues.

Maintenance, upgrade cost and the MIT licence

The repository is not archived, and the last push was on 2026-07-01. That is the fact to weigh; the release list shows v4.0.0-alpha.8 on 2026-06-18 and two alphas on 2026-07-01, so the 4.x line has been moving in alpha increments rather than landing a stable tag.

The practical upgrade cost sits in two places. The first is Node: any environment below 22.15 fails the declared engine requirement, so a build image upgrade may be a prerequisite for a package upgrade. The second is the module boundary. Because the package is "type": "module" and the require path goes through a feature test, a consumer on CommonJS is exposed to changes in that test in a way an ESM consumer is not. Neither cost is documented in the README as a migration note; the README points to the docs site instead.

The licence is MIT, declared in package.json and present as a LICENSE file at the repository root. MIT is permissive: it allows use, modification and redistribution with the licence and copyright notice retained. That is a statement about the licence text, not legal advice, and it says nothing about the licences of the addons you choose for WebC, Sass, Vue, Svelte, TypeScript or JSX. Check those separately, because they are separate packages. Funding for the project is listed as Open Collective, not as a paid tier.

Editorial conclusion

Adopt Build Awesome if you want a JavaScript static site generator that reads a directory of mixed templates and emits HTML, and if you are comfortable running Node 22.15 or newer. Do not adopt it if you need a stable tagged release: package.json on main declares version 4.0.0-alpha.10, and the recent releases are v4.0.0-alpha.8, v4.0.0-alpha.9 and v4.0.0-alpha.10, all alphas. Before you commit, verify three things in your own tree: that your Node version satisfies the engines field, that your chosen template languages are the ones the README lists (HTML, Markdown, JavaScript, Liquid, Nunjucks, with addons for WebC, Sass, Vue, Svelte, TypeScript and JSX), and that the package name you install is the one you intend, because the README gives both @awesome.me/buildawesome and @11ty/eleventy as install targets.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes