The Great Unlearning Doc

[nickchomey]

Someone proposed the creation of a "The Big Unlearning" guide in discord. I and others have also floated such a thing various times. I'm not the one to write it, but figured that we can start to dump/brainstorm ideas here for inclusion in such a doc.

Here's some things that I had to wrap my head around/learn

• SSE is HTTP so is compatible with all (is that true?) HTTP stuff.
  • e.g. You can add gzip, brotli, zstd compression as you would for any http response - be it in your application (d* bad apple example does this) or in a proxy server (caddy, nginx, cloudflare etc). I documented a lot of that in this issue.
• D* does not just open one SSE connection that everything gets piped through from the server - like you might do with WebSockets. Each request is a new http request that happens to have SSE headers and can therefore return nothing (eg POST data), 1 message and close (request-reply pattern) or infinite responses (long-lived SSE connection). You could also, in theory, maintain multiple long-lived connections for different endpoints. If using http2+ it shouldn't really be an issue since, in theory, you could have infinite requests sharing the same multiplexed connection.
• this video and article really ought to be featured more prominently
• Dont be afraid of sending an entire document for morph/merging rather than more granular elements (in fact, it might even be better/more performant
• Its HOWL - you dont need any particular backend, let alone NATS/event-driven stuff. But its plays particularly well with such an approach (and NATS is just glorious compared to its alternatives)
• idiomoprh is the appropriate default for merge-fragments. Use it as much as you can, unless you're truly just appending/prepending a fragment somewhere - then it might be appropriate to change the mergeMode.
• You also dont need to specify the data: selector #foo if the fragment contains an ID (as it should) - idiomorph will just find it and deal with it.
• This all makes D* is particularly compatible with brownfield apps, as you dont need to modify the html templates as you would with something liek htmx (eg adding hx-swap, hx-target etc...). Just send the fragment with the ID and/or data: selector and it will work.
• Should probably elaborate on this compared to hx-boost

And some "collected wisdom" from discord:

10 commandments (and some of my own additions/elaborations)

1. SSE is just HTTP response with ability to send 0- ♾️ chunks
2. SSE it cost the same as any fetch.
3. Yes its a framework, it is also a library.
4. D*'s superpower/contribution to hypermedia is making signals easy to use declaratively
5. But try not to use signals until you need them(theyre at the top of hypermedia maslow hierarchy of needs

• theyre most useful when the dom and its elements are stable and you just want to change the content (name, time, date, price etc...). Fragments are the Bricks of your house, they alone hold together and can last a while on their own but signals are the mortar than can flex and hold together your house when rain and wind comes. If you are building a simpler fire pit, bricks alone are fine... building a cathedral, you have well place mortar thoughtfully placed too much mortar and the whole thing collapses
• immediate vs retained mode (i believe immediate is essentially hypermedia/MPAs whereas signals are retained mode. Use each when appropriate?

6. Don't put state in the wrong place (keep it on server - or at the very least in service worker proxy, not in a SPA)
7. Don't over complicate it
8. Hypermedia is faster than you think
9. CSS and View Transitions hide any server work
10. Just start coding with it, it's easier than you think
11. :NotACult: but 🖕 JS

[delaneyj]

It's covered a bit in #9 but should definitely talk more about embracing the browser features...

1. CSS animations are hardware accelerated
2. Speculation rules
3. View transition API
4. etc
   It shouldn't be unlearning but I've seen so many people think D* needs to wrap things that are already declarative. Learn what the platform can do and leverage native features.

[nickchomey]

This isn't an unlearning, per se, but its something worth keeping an eye on. From the dev of Lit, and collaborators who are working on the Signals Proposal and other related stuff

[templates] A declarative JavaScript templating API

Delaney's comment on it: "if we had a declarative API in the browser then D* would be about 1KiB and then plugins"

The whole thread is a fascinating read

[nickchomey]

Im going to put this here, because the whole blog (from a veteran of the Web - development, browser engineering, standards etc...) is dedicated to Unlearning people - particularly about SPAs, and especially React.

There's 4 different series, each with many exceptional posts. Required reading for anyone interested in web dev
https://infrequently.org/series/

[nickchomey]

You can make your own bundle with this file: https://github.com/starfederation/datastar/blob/develop/library/src/bundles/datastar.ts

Just select what you want to import. and before the DS.load, you can change properties.

e.g. if you want to rename a plugin, you can just set Persist.name="ds-name" if you want the attributes to be e.g. namespaced (eg. data-ds-name) or altogether different (Persist.name="storeForLater" for data-storeForLater)

Can just use existing plugins as a template for creating your own. Then import to the bundle script above and build

[bencroker]

This reads very much like your personal (un)learning journey, which makes for a great read (my own was very different)! Would you consider turning it into an article? A lot of what you noted is already spread throughout the docs, some of it feels like it doesn't belong in the docs, and we could really use some community contributed articles about Datastar. We can, of course, link to it from the official docs.

[nickchomey]

Yeah, not all of it is doc-worthy. As noted, was just dumping thoughts here and hoping others would do the same so they could be curated into something useful.

Perhaps you and others could share your unlearning experiences, as well as any insights, gotchas etc that you had/think others might have?

I'd be happy to them curate it into stuff appropriate for a doc, and stuff better left as articles.

As for me writing an article, I don't publish anything anywhere. Is there somewhere d* would want to publish it?

[bencroker]

As for me writing an article, I don't publish anything anywhere.

That’s a shame, you write well.

I’m not sure what to do with your notes besides refer back to them next time I’m adding to the docs. I have some higher priority things on my list such as documenting the SDKs, reviewing all examples, etc., but some of these points will be good to have as reminders, thanks!

[nickchomey]

Again, this issue was meant as a place for other people to share their own struggles/discoveries so that something useful could be curated from it. Closing it now and putting the focus solely on my struggles defeats that purpose.

And, to clarify, I'm happy to help with that curation and doc writing. I was just saying that I don't have or want any online writing presence of my own.

If you'd like help with proof reading all of the docs/examples, and also feedback on it all from the perspective of a relative newcomer, I'd be happy to do so. As I've said in various places, I think the docs tend to assume more knowledge than many people actually have. But it wouldn't take much to fix that.

[bencroker]

Understood. We use GitHub issues as actionable items that can be completed, rather than long-term storage of ideas. What you're describing might be better as a GitHub discussion or a shared document. Help with docs is always welcome!

[nickchomey]

Sorry, understood! Perhaps you could convert this to a discussion. Apparently there should be an interface like this somewhere in this page?