HTML5 Boilerplate ships a dist folder, and its npm package is at 9.0.1 from 2024

dist/ is the product and the rest of the repository is the factory

The project is unusually explicit that the repository and the product are different things. The material you are meant to consume is the contents of the /dist/ folder, and everything else in the repository exists to author the project. Some of the tools and processes you see are solely for the production of HTML5 Boilerplate and are not part of it, and the gulpfile.mjs script is named as the example: it builds the project and is not part of the project itself. The analogy offered is that you do not clone vuejs/core to create a Vue.js app. What that cannot do is serve as a starting point for your own site. If you clone this repository expecting a template to edit, you have cloned the workshop instead of the product, and the first thing you have to do is find the build output rather than start writing code.

The four quick start options hand you four different versions

There are four ways in, and they are not four spellings of the same thing. The create-html5-boilerplate script fetches the latest npm published package, or any version available on npm. The Template Repository creates a new GitHub repository based on the latest code from the main branch. Installing with npm or yarn gives you the published package, whose dist folder represents the latest version for end users. The downloadable zip is a snapshot of the dist folder from the last stable release. What this cannot do is give you a consistent answer to what you just installed. The npm channel and the release zip trail the tagged releases, while the Template Repository hands you unreleased work from the default branch. Pick the channel first, then the method, or you will end up comparing code from two different points in the project's history.

The npm path makes you copy the folder yourself

Installing the package is a single command, either npm install html5-boilerplate or yarn add html5-boilerplate. What arrives is a package whose dist folder, at node_modules/html5-boilerplate/dist, represents the latest version of the project for end users. And then the instruction that matters: depending on what you want to use and how you want to use it, you may have to copy and paste the contents of that folder into your project directory. What this cannot do is scaffold anything. There is no create flag and no generator, because the package is delivered in the shape of a library rather than a template, so the real work of adopting it is the manual lift out of node_modules and into a directory you control and can edit. If you expected an install to write a starting site for you, this is where that expectation ends.

Unzipping from a terminal needs a directory you create first

The release zip is a snapshot of the dist folder, and the guidance differs by how you open it. Unzipping on Windows, on Mac, or from the file manager on Linux will output to a folder named something like html5-boilerplate_v9.0.0. From the command line you will need to create a folder and unzip the contents into that folder, because the archive has no directory to land in:

mkdir html5-boilerplate
unzip html5-boilerplate*.zip -d html5-boilerplate

What that cannot do is save you the step, and skipping it is the failure mode here. The archive contains the dist files at its root rather than a wrapping folder, so without the mkdir the unzip has no target and you end up with loose files in whatever directory you happened to be standing in, which is a messier outcome than the one the file manager would have given you.

The npx path fetches without dependencies, then asks for them

The create-html5-boilerplate script is described as fetching the latest npm published package with npx, npm init, or yarn create, without having to install any dependencies. The three-step sequence it prints then does install them:

npx create-html5-boilerplate new-site
cd new-site
npm install
npm run start

So the dependency-free part is the fetch, not the run. What the shortcut cannot do is get you to a working page on its own, because the very first action after the folder appears is a full dependency install and then a start script. The version it pulls is whatever npm currently publishes, which is a separate question from what the release zip contains. Treat the npx route as a convenient way to materialize the published package in a directory of your choosing, not as a way to bypass setup.

Contributing needs Node 22, and the test run rebuilds an archive first

The package manifest sets engines to node >=22 and pins Node 22.23.1 through a volta block, so the authoring toolchain asks for a current runtime rather than accommodating an old one. The scripts are short: build runs gulp build, lint runs eslint ., and the test script is:

gulp archive && mocha --reporter spec --timeout 5000

What that test command cannot do is run as a pure unit test pass. The gulp archive step executes first, which means the suite consumes the assembled release artifact rather than reading src/ in isolation, so a failure can mean either a real regression or a packaging problem. The dependencies behind those steps are visible in devDependencies, including gulp with its autoprefixer, header, rename, and eslint-new plugins, plus mocha, eslint, prettier, archiver, del, and main.css. Contributors also carry the formatting cost, since the prettier script rewrites js, json, md, mjs, and yml files across the tree.

The published tarball ships five entries and nothing else

The files array in the manifest is short: CHANGELOG.md, LICENSE.txt, package.json, dist/, and README.md. That is the whole npm payload, and it excludes src/, test/, docs/, gulpfile.mjs, and eslint.config.mjs. The manifest also carries a config block that maps the four working directories, naming archive, dist, src, and test. What this cannot do is give you the project's own build. Anyone who installs the package receives the template and nothing that produced it, so the gulpfile, the source, the test suite, and the documentation sources are all reachable only through a git clone. The offline documentation claim in the project refers to the documentation bundled with the shipped template, not to the docs directory in the repository. Read the files array as the boundary between consuming the template and working on the template.

The npm package is 9.0.1 while the default branch has moved two years ahead

The release history is old relative to the commit history. Version 9.0.1 shipped on 2024-04-16, 9.0.0 on 2023-12-06, and before that 8.0.0-RC2 on 2020-06-04. The repository itself was last pushed to on 2026-09-14, and the manifest still declares 9.0.1. What that gap means is that the word latest is doing different work depending on the channel: the npm package and the release zip are two-plus years behind the default branch that the Template Repository copies from. A reader who takes the zip, then reads the repository, is looking at two different codebases. The same drift applies to browser coverage, which is defined by the default Browserslist configuration rather than a fixed list in the project, so what the template supports is decided outside the repository and can move without a release.

Editorial conclusion

HTML5 Boilerplate fits a team that wants a considered set of defaults rather than a framework opinion, and that is willing to copy a dist folder into its own tree. It does not fit anyone expecting a toolchain that scaffolds a project for them, because the package deliberately stops at a folder you lift yourself. Before you commit, confirm which channel you are taking, since the npm package is at 9.0.1 from April 2024 while the default branch has moved on since, and check that Node 22 or newer is available if you intend to build it.

Frequently asked questions

Official sources

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