For people who are confused: Hyperclay is a NodeJS server and frontend JS library that allows HTML pages to update their DOM and then replace their own .html source with the updated version.
Imagine clicking a checkbox, which adds the `checked` attribute to its element, then using Hyperclay to globally persist this version of `document.body.outerHTML`, so that it's there next time someone visits the page. There's automatic versioning and read/write permissioning.
It's a pretty cool project! I'll definitely try for my own personal tools.
Do note that, from my understanding, it's most useful when there's one developer who is also the only content editor. Otherwise you'll have editors overwriting each other's changes, and if there are multiple copies there's no easy for the developer to push a change to all copies.
I'm still confused - if it requires a NodeJS server, then it wouldn't be a fully self-contained HTML file would it?
It technically doesn't say "self-contained", but it does say "portable" and "self-updating", which I must agree is misleading.
If you want something actually self contained play with this https://startr.style/modernism/
This thing comes across so pretentiously, but they have some really novel CSS ideas I might try. The idea of making selector based on [style*="--bgc:"] and using that to set background color like style="--bgc: red" is not something that I would have thought of.
Happy you enjoyed it. Most of my creations just build on and with Startr.Style. It's a tight alternative to Tailwind's mess of classes. I especially love how directly it translates to pure styling yet allows us to have responsive design eg add the -md suffix to --bgc to specify background colors for tablets and up.
When I work on Modernism or any of the other experimental pages on https://startr.style I don't do it with any pretension but out of a love and familiarity of code and what the web can be. As child I traded helping out at a local computer store for time exploring Gopher and then Mosaic's window to the web.
I appreciate your efforts :)
I think what gets me is there's 6 paragraphs in a row that either start with "Modernism" or have it in the first sentence, and it comes along with words like "transcends", "echoes", "essence", "exude", "crafts." They're good paragraphs by themselves and make good points, I just think that together they come out a little breathless, and maybe some consolidation is in order :)
I notice from your profile that you haven't submitted your site to HN, I think you should do so, I think it would generate some interesting discussion.
That was cool! Thanks for sharing.
You're welcome!
In my perspective, for truly "self-contained", "portable" and "self-updating" and even "un-hosted" web apps, the only option nowadays are prehistoric data-URIs, that are slowly losing abilities anyway (basically can live only as bookmarks or direct URL pastes, and their only persistence option is location #hash that needs re-bookmarking):
You probably wouldn't fault another piece of software for calling itself single-file even if it requires an operating system to run. It makes more sense to look at from a (build-)artifact POV - ignoring the foundations the artifact rests on if they're not specific to it.
[dead]
I added this word-for-word to the home page. Thank you!
Note: we are working on a way for a developer to push "DOM-based schema migrations" to all forked apps.
I'm flattered you liked my description so much! It's a really special project, thanks for sharing it.
I love this, I think this brings "block editing" capabilities to the masses, which is a big selling point for WordPress. In recent months, I've been looking at micro-sites and I concluded that Carrd is king for this type of landing pages/microsites. So this looks very promising for this respect. Either of you care to share or dispel security concerns or describe attack surface? For the past 6 months I've been looking at HUGO sites and the simplest deployment approach I found was alpine/sqlite/hugo containers at 5-10mb in size. Is there a way to delegate control/editing of sections/pages? I think the world needs a simple platform to build sites and delegates sections to respective departments/units. The only platform which seems solid for this is drupal, but it's kind of overkill for SMB orgs.
Thanks. Author mentioned TiddlyWiki as inspiration. But the whole point of TiddlyWiki was that it doesn't need a server right?
So I'm trying to understand the difference, the payoff. I understand that local web APIs are ass and you very quickly run into the need for a server.
But I'm wondering about the utility of combining the two approaches. It seems like a contradiction in terms. Here's a server to help you with your dev setup oriented around not needing a server.
I guess the main win would be cross device access? You have it online and you can edit it easily.
I'm editing my stuff on my phone in a text editor. And syncing it to my laptop with a sync app.
Thanks. Author mentioned TiddlyWiki as inspiration. But the whole point of TiddlyWiki was that it doesn't need a server right?
I did a deep dive on TiddlyWiki recently. No, it doesn't need a server; an entire site can be self-contained in one HTML file.
If you want to run it as a multiuser, web accessible wiki, it runs on top of NodeJS.
Turns out, the original TiddlyWiki used a java jar to handle the file persistence. (I remember it being so magically automatic, but recently investigated how it was done)
I don't think that's right - IIRC it used to be possible to write out a file, if loaded from a file:// URL, directly from JavaScript. Then that ability got nobbled because security (justifiable) without properly thinking through a good alternative (not justifiable). I mourn the loss of the ability, TiddlyWiki was in a class of its own and there should have been many more systems inspired by its design. Alas.
ETA: Wikipedia has reminded me the feature was called UniversalXPConnect, and it was a Firefox thing and wasn't cross-browser. It still sucks that it was removed without sensible replacement.
I used TiddlyWiki a lot to manage my D&D 3.5 campaign back in the day. As I recall, it originally was a true stand-alone HTML document capable of overwriting itself, but once browsers dropped support for this capability, users had to begin using various workarounds, and this remains the status quo today.
TiddlySaver.jar was one such workaround. A check in the Wayback Machine suggests that it was originally required only for Safari, Opera, and Chrome; IE and Firefox needed no such plugin. Nowadays, there are several workarounds, and setting up one is a mandatory installation step: standalone applications, browser extensions, servers, etc. Some are clunky (e.g. you have to keep your wiki in your Downloads directory or the browser can't write to it), and either way, TiddlyWiki is no longer truly a single stand-alone HTML file, at least not for writing purposes. It's still a very versatile tool, though.
How would TiddlyWiki write to filesystem (save) without a server?
I thought opening index.html in the browser was basically just a demo.
TiddlyWiki can replicate itself. All users can freely edit any TiddlyWiki and save their changes to their filesystem. There's a few options for exports.
It is a common gotcha that new users will lose some of their work while they learn persistence.
Tiddlywiki has two modes of running. In one, you simply save the file as HTML and all your content is saved inside the file.
The other mode is with a nodejs server (it's what I'm using). This allows me to access the wiki from all devices.
I see, so you make edits, the Javascript edits the html, therefore File -> Save Page will download an html file with your changes in it that you can open again.
I forget that File -> Save is even a thing for websites.
Note: The TiddlyWiki documentation explicitly advises that File -> Save Page does not work.
You have to click a save button in the app, and it will generate a valid copy. However, most users deploy some plugin or software which allows transparent auto-saving.
I used https://github.com/slaymaker1907/TW5-browser-nativesaver, that still works with the current version 5.3.8, though just in Chromium based browsers. You save the file once and from then on, as long as the tab is open, it autosaves itself.
That said, I advise against Tiddly Wiki, after using it for long. It has multiple bugs, which the author won't fix (e.g. div's inside p's), It has a cryptic syntax (e.g. code in attribute values), and tagging is not implemented in a way which makes a wiki scale (well, technically it is, tags can have tags). It is a thing where features are added but nothing outdated gets deprecated, so it is bloated. One will be more productive by using a folder with markdown files, and a browser add-on like Markdown Viewer.
I don't know, for me it works, but I don't do anything fancy with it. I just put it on a server, so I can access it from all my devices. I don't even use tags, just tiddlers with sources which are other tiddlers or external web pages.
My solution to a lot of issues is to use Tiddlywiki Classic. No divs inside p that I can find, less bloat (412 KB for a blank file instead of 2.5 MB), and it's still maintained. The main advantage, to me, is that it fits more tiddlers on screen at a time, which is the main point of TiddlyWiki for me; TW5 adds large amounts of spacing, borders, and large font sizes, which looks nicer but is less practical.
It's not perfect, though. Paragraphs are rendered by using two br tags, instead of p tags. Link syntax is the reverse of MediaWiki syntax; i.e. [[foo|bar]] links to "foo" in MediaWiki, but "bar" on TiddlyWiki, which trips me up constantly. There's other syntax awkwardness like sensitivity to spacing and newlines. Journals sort in alphabetical, not chronological order.
<https://classic.tiddlywiki.com/>
iirc browsers used to allow direct filesystem access.
They never did, if anything it's the opposite in that I think there are now APIs that can make this possible.
With TiddlyWiki you had to essentially File -> Save As and save the HTML back over itself. There were other ways too but they were all workarounds to the issue that browsers don't allow direct access.
They did back around 2008. I used Wiki on a stick - see https://stickwiki.sourceforge.net/which was kind of neat) but after a few years, Chrome etc stopped letting it save itself.
Thanks for the description, I kept reading the webpage and didn't understand what the project was or how it worked. Yours is really succinct and clear.
To be completely honest, I don't see how this is more useful than adding a sync layer to localStorage. I did make a service that does that at htmlsync.io and am genuinely curious how this solution is better.
Just like with https://tiddlywiki.com/
Your notes are the HTML file! You can keep it in your documents folder, sync it via any service, track it in version control, etc. It’s for folks who know what the filesystem is, don’t know how to host a server (or don’t want to), but want a website-like experience. Works offline, too!
So like, Obsidian, but for HTML?
The file itself provides both the dynamic functionality and data storage, but you need an engine (like obsidian) to make the data persistence and dynamic parts work together. I.e. if there is a button that adds a task to a todo app, your engine modifies the HTML file with the new content.
I finally also recalled this project (tiddlywiki), but CMIIW, the statefulness of the hyperclay is only for developers, the end user will get the same conventional html. Without some kind of common solution/protocol/standard on the browser side that would allow persistence it's not so exciting. Theoretically there might be some kind of simple protocol that would save html file versions on the server based on the cookie, but there are so many ways this can go wrong
This all sounds like something from 2001. I was doing pretty much exactly this around 2001, using contenteditable with an IIS/JScript back-end.
I think contenteditable is more akin to a rich-text document, while Hyperclay goes a bit beyond by allowing JS to edit the DOM too. I think Smalltalk images and virtual machines are a closer comparison, but applied to the web. You download the image, with some running code, use it, and persist the whole application state.
> while Hyperclay goes a bit beyond by allowing JS to edit the DOM too.
So revolutionary!! How did they achieve this technical feat!?
Yeah, sounds like Tiddly Wiki or similar except with the need for a backend component.
Edit: actually it looks more like a library/framework to make such apps. And now I'm not sure if it needs a backend component or nodejs or not.
The idea would work a lot better with something like Cloudflare Workers. You don’t really need it to run 24/7 and it would fall into the free tier.
If I need a server to run this then surely I can use sqlite and save different versions of the page without overwriting the html page every time.
How does this differ from htmx?
htmx is a javascript library that reads configuration from html attributes and sends http requests based on that configuration
hyperclay is a web server that stores and serves versions of html files
htmx requires a server. This enables a single html file to modify itself.
But it needs a server too?
No, this need a server too. Everything that saves changes to non local (shareable) locations needs some kind of a server. The best solutions are of course when OP hosts the server and you pay for it /s
So it's a wiki?
I don't get it.
Wiki has specific content you can add. New article, body of an article, etc. This lets you change all the html. With this, you could edit your wiki into a calculator.
I like it!