Everyone I know reaches for a framework before they've finished the sentence describing what they're building. Next.js for a landing page. A full CMS for a project retrospective. I've done it too.
But over the last year I've shipped 50+ single-file HTML pages — reports, explainers, dashboards, interactive demos — and I've become convinced the humble .html file is the most underrated medium on the web. Here's what I learned.
1. One file forces one idea
When your entire page lives in a single file, scope creep becomes physically painful. There's no components/ folder to hide half-finished ideas in. Every section has to justify its existence, because you can feel the file getting heavy. This constraint produces tighter writing and clearer structure than any linter ever did for me.
2. A URL beats a repo
The moment someone can open your work in a browser with zero setup, your distribution changes completely. "Clone this, npm install, ..." is a funnel with 90% drop-off at each step. A link is a funnel with one step. For anything meant to be read rather than run — reports, proposals, visual explainers — a single file shared via URL will reach 10x the people.
3. Own your bytes
A single HTML file is the most portable artifact in computing. It works offline. It works in 20 years. No build step to rot, no dependency to deprecate, no platform to shut down your account. I've re-opened pages I made a decade ago and they render fine. Try that with a framework project.
4. Know when NOT to do it
Single-file breaks down when: you need a database, you have more than ~3 distinct page types, or multiple people edit concurrently. It's a medium for documents and demos, not applications. Respecting that boundary is the whole trick.
Practical tips that actually matter
- Inline everything, but watch the weight. CSS and JS inline is the point — but base64 images balloon fast. Keep total under ~500KB or split images out.
- Design for the phone first. Over 60% of my page views are mobile. If your layout needs horizontal scrolling on a 390px viewport, it failed.
-
Print styles are free goodwill. Five lines of
@media printCSS makes your page genuinely useful as a document. Nobody does this; everyone appreciates it. - Semantic HTML is your SEO. No framework, no meta framework — just real headings, real paragraphs, alt text. It works.
The takeaway
We rebuilt the web to be programmable and forgot it was supposed to be readable. Before you scaffold a project, ask: could this just be a really good HTML file? Half the time, the answer is yes — and you'll ship it today instead of next month.
Top comments (1)
tr.ee/dev-to