Single HTML Files as Self-Modifying Web Applications
Imagine if making software felt like sculpting clay. No compiler, no backend, just shape the interface and you shape the app.
Today, building a simple digital tool means wrangling a stack of tools: a framework, a runtime, a database, a deployment pipeline, and brittle integrations between them. We've come to accept this complexity as the price of software. Hyperclay asks: what if we didn't?
If you were to pick up a block of clay and shape it, you'd expect it to stay in its new state. If you cut it in half, you'd expect to see, locally, an internal structure that helps it maintain its form. And you'd expect to be able to give it to someone and allow them to shape it too.
These intuitive and natural aspects of physical objects are things we take for granted with powerful software systems, like Google Docs or a photo editor. We can mold digital objects with them and then share the results.
But when it comes to making a new type of digital object for ourselves &mdask; with its own UI, state, and behavior &mdask; we end up orchestrating the background processes that maintain the illusion of software being an object rather than building the object itself.
Hyperclay reimagines personal software development as single, self-contained, self-modifying HTML files that can persist themselves. By treating the DOM as simultaneously the source code, runtime, database, and UI, we eliminate multiple levels of complexity from modern software stacks and create a new malleable software primitive you can shape in real time.
As you shape the UI, you shape the application.
Through novel techniques like packaging the editable UI and view-only UI into one, the save-strip-restore cycle, and the DOM-as-state-machine pattern, Hyperclay makes software development as immediate and tactile as working with physical objects.
Hyperclay isn't just a concept — it's a platform and framework that makes single-file apps easy to build:
- Live, unified environment: The document IS both source code and runtime - edit and see changes instantly, no refresh needed
- Declarative attributes for state and behavior: Simple attributes like
persist,onclone,trigger-save, etc. - Save-strip-restore cycle: Seamlessly switch between edit and view modes in one file
- Self-modifying saves: Changes automatically persist back to the HTML file itself
- Built-in versioning: Revert to previous states without manual backups
- DOM as database: Structured patterns for managing state directly in HTML
Example: Building a checklist app
<input type="checkbox" persist> Task 1
<input type="checkbox" persist> Task 2Checking boxes automatically saves state to the web. No LocalStorage code, no save buttons, no complexity.
Without Hyperclay:
<div id="tasks"></div>
<script>
// ❗️Requires: API server, database, hosting, auth system, many dependencies
axios.get('/api/tasks').then(({data}) => {
data.forEach(task =>
renderTask(task)
);
});
function updateTask(id, completed) {
axios.put(`/api/tasks/${id}`, {completed});
}
</script>See Hyperclay in action with these fully functional example applications:
- Dev Log: A personal work log with custom UI for updating content and novel controls for cycling through project categories. Uses the DOM as both state machine and database.
- Writer: A genuinely useful app for publishing rich writing with support for images and syntax highlighting. Demonstrates using the DOM as a JSON database with a script tag.
- Kanban: A beautiful and functional kanban board showing how an entire visually appealing UI can become a functional app with minimal jQuery-like code.
- Landing: A fill-in-the-blanks landing page builder that helps people with project ideas hit the ground running. Demonstrates advanced features like markdown popovers and undo/redo stack.
I discovered that distributing your own software can be as simple as creating a self-modifying HTML file. The key insight: software is, fundamentally, allowing users to shape the light that comes through their screen. If we make the thing being shaped the application itself, the stack collapses down into a single thing with a wholeness and oneness not obtained by most software.
Most frameworks reduce complexity by adding abstractions; Hyperclay reduces it by removing them. This isn't just the technical optimization of removing layers from the stack; it's a new type of application that's portable, self-contained, and intuitively comprehensible. Researchers should know that by embracing "locality of concern" over "separation of concerns" and treating the DOM as the single source of truth, we can merge the concept of the UI with the concept of the database and give users the feeling of an object they can hold in their mind.
Building with this malleable primitive gives the feeling of holding something you can shape instead of the feeling of being inside a larger system you have little control over or knowledge of.
Hyperclay builds on several lineages:
- Spreadsheets (VisiCalc, Google Sheets): The canonical example of live programming where data and computation unite, but Hyperclay extends this to full web applications
- TiddlyWiki: Self-contained wiki in a single HTML file, but Hyperclay generalizes beyond wiki functionality to arbitrary applications
- HyperCard: Shares end-user programming through direct manipulation, but Hyperclay uses standard web technologies rather than proprietary formats
- Smalltalk: Image-based persistence where code and data are unified, but applied to web documents instead of virtual machines
- Emacs: Self-modifying environments where the tool can edit itself, but using HTML/DOM instead of Lisp
- Wiki systems: Embraces Ward Cunningham's editable web, but extends editing to include behavior, not just content
- Webstrates: Collaborative malleable web documents, but Hyperclay prioritizes single-file simplicity and portability over collaboration primitives
- Observable/Jupyter: Immediate feedback and literate programming, but producing standalone applications rather than notebooks
Hyperclay differs through its radical commitment to single-file architecture and using the DOM itself as the database, eliminating the need to integrate different high-level systems while maintaining standard web compatibility.
Hyperclay trades the power of connecting to larger systems for the certainty and learnability of a single system that is whole and complete in itself:
- Data processing: Without a backend, Hyperclay is limited to what the browser can do on a single page
- Scale boundaries: Single HTML files work well up to ~100,000 DOM elements; beyond that, browsers struggle
- Security model: Everything in the document is visible to all users — no secrets, no complex permissions
- Collaboration limits: No version control, branching, or merge conflict resolution beyond simple ownership
- Performance ceiling: Save operations transmit the entire document (typically 50KB-5MB), which can be an issue on slower networks
Unsolved problems include:
- How to maintain wholeness while enabling composition across documents
- How to preserve portability when documents reference external resources
- Whether or not visual programming can lead beginners to explore the source code and modify their own applications
- The deeper challenge: shifting from industrial-scale to personal-scale thinking about software
Adoption could follow multiple paths: end-users discovering useful apps and gradually learning to modify them, developers seeking refuge from stack complexity for personal projects, or teams needing quick internal tools without infrastructure overhead. The key is meeting people where they are—whether they're non-coders who want to tweak an app or experienced developers tired of boilerplate.
The key philosophical tension: is it possible to maintain the tactile feeling of a single thing that has oneness and local malleability when it's connected to the wider internet, which always wants to connect to and expand the potential actions of the things connected to it?
The Hacker's Manual for Hyperclay
Deep dive into the philosophy and technical architecture
- Hyperclay.com: Run HTML apps in the cloud
- Documentation: How to build HTML apps
Download and run Hyperclay locally to experience the magic of self-modifying HTML applications: