One file, no build: shipping client sites as a single HTML document
No bundler, no dependencies, no deploy pipeline. Just one document a client can open anywhere and still understand in five years.
Somewhere along the way, shipping a five-page marketing site started requiring a toolchain with more moving parts than the site itself. A framework, a bundler, a CI runner, a hosting platform with its own CLI. All of it justified, none of it necessary. For the past year, almost every client deliverable that left this studio has been a single HTML file: markup, styles and behavior in one document, working from a double click.
This is not nostalgia. It is a deliberate constraint, and like most good constraints it does more work for you than against you.
Why one file at all
A single file has properties no pipeline can give back once you lose them. It is portable: it travels over email or a USB stick and arrives working. It is inspectable: the client, or the next developer, opens it and sees everything there is. It is durable: there is no lockfile to rot, no dependency to deprecate, no build that stops reproducing two years from now.
The constraint also disciplines the work. When every kilobyte lands in one document, you feel the weight of each decision. A second font family, a carousel library, another icon set: each one becomes a visible cost instead of an invisible install.
The moment a deliverable needs a README to run, you have shipped a project, not a product.
A rule we keep on the studio wall
Multiple pages, one document
Clients still want pages. The answer is a hash router: every page is a section in the document, and the URL fragment decides which one is visible. The whole thing fits in a small self-contained function and needs no framework.
(function () {
"use strict";
var routes = {
"#/blogs": "view-index",
"#/blog/one-file-no-build": "view-article"
};
function render() {
var id = routes[location.hash] || "view-index";
document.querySelectorAll(".view").forEach(function (v) {
v.classList.toggle("is-active", v.id === id);
});
window.scrollTo(0, 0);
}
window.addEventListener("hashchange", render);
render();
})();
The router this page is running, minus titles and scroll tracking.
The back button works, links are shareable, and the browser handles the state. Sixty lines covers parameters and page titles. This page needs fewer than thirty.
Images, fonts and placeholders
Assets are where single-file design either succeeds or collapses. The rules we hold to:
- Fonts come from one host, two families at most, with weights listed explicitly. Everything else falls back to the system stack.
- Decorative surfaces are CSS. Gradients, borders and generated texture weigh nothing.
- Photographs get a tiny base64 preview painted first, swapped for the real image once it arrives. A soft placeholder beats a spinner every time.
The validation pass
One file means one blast radius. A single unclosed tag can silently eat half the page. So nothing ships without a short automated check: tag balance across the markup, a syntax pass on every script, and a character scan on the stylesheet. It takes seconds, runs on every revision, and has caught a real defect every single week since we made it mandatory.
The lesson generalizes. Removing the toolchain does not remove the rigor. It only lets you choose where the rigor lives.
Where the approach ends
A single document is the wrong call when content changes daily, when you need server rendering at scale, or when the markup crosses roughly half a megabyte. At that point you want a real backend, and we will happily build one. But for storefront themes, campaign pages, dashboards, and this journal, the single file is not a compromise. It is the professional option most teams forgot was on the table.
