HTMX & Umbraco: Powertool meet Powertool

Umbracians, as far as I can tell, are mostly shielded from the online noise surrounding server-side and client-side rendering/environments. Many of us prefer to render our pages server-side, passing nicely typed view model objects into Razor templates, rarely considering much else. While we seem to put more energy into helping each other out and building our own special Umbraco ecosystem, the greater web development landscape has been convulsing through an identity crisis. This drama and sometimes cognitive dissonance-inducing chaos are partially fueled by a mix of a new class of YouTube-promoted software developer influencers, as well as promises of easy six-figure salaries from coding bootcamps.

At first glance, it appears that ReactJS and NextJS are the cause of this strife, but if you zoom out, this is really a battle between client-side and server-side rendering. And if you really zoom out, you’ll notice that it’s more of a question of whether the web platform should be treated as a distributed application platform, something that competes with the native environments, or if the web should be preserved as the hypermedia system it was conceived as.

Many have lamented the popularity of the web application platform direction, but perhaps the more comprehensive, well-thought, and contrarian writing comes from Carson Gross in his book, Hypermedia Systems.

If you’re unfamiliar with his short and easily digestible ode to hypermedia, it’s part reintroduction to hypermedia, and part tour of how to use Carson’s HTMX library. Hypermedia Systems is thorough and well-written, and the reintroduction section does a great job at rewiring your brain from thinking “this is the old (jQuery) way to do this” to embracing a refreshed approach to creating dynamic and interactive websites.

For the first time, I had seen vocabulary to describe what I was observing elsewhere, and I became completely captivated and started figuring out how I could layer HTMX on top of Umbraco.

You should absolutely read his book (it’s free), but in this article I’ll cover a few highlights to pique your interest, and then demonstrate how we too, Umbracians, can enhance our websites using a hypermedia approach.

Defining a Hypermedia System

What is a hypermedia system? It’s a networked architecture that contains digital media (text, images, videos), which are wrapped in structure (HTML tags), and the content contains hyperlinks to other content (in our case, these are simple a=href’s). All three elements are returned together in a single response from the remote host.

This soup of content, markup and navigation is returned to a user agent (for example, but not limited to!) a web browser, which is then presented to the end user. The user agent is responsible for a single thing - presenting the content in its interface, however it pleases. In a hypermedia system, the user agent does not store or maintain state; instead, that responsibility is largely ejected out to the remote host, and no two responses are guaranteed to return the same content or outward navigation.

It all seemed so exciting - hyperlinks! - and it was in the early 1990s. By the mid-1990s, forms were added to the HTML spec with version 2.0, and additional verbs were added to the HTTP protocol, resulting in HTTP 1.1. This prompted Marc Andreessen to boldly proclaim Windows as a “collection of badly debugged device drivers.”

“Netscape will soon reduce Windows to a poorly debugged set of device drivers.” - Marc Andreessen, 1995

Later, Roy Fielding brilliantly distilled his understanding of this architecture, describing what we know today as a REST API. That is, receiving partial responses of HTML as valid behavior.

Yes, you read that right - a single REST API response should return fragments of content, structure, and navigation. And herein lies one of Carson’s often repeated gripes - a JSON API is not a REST API, it’s a data API. Carson argues that the field of web development has been corrupted by the latter definition, a complete rewrite (or misunderstanding) of Roy Fielding’s definition! Outrageous!

The tragic result of this misunderstanding? We’ve shoehorned the older (yes, older) thick-client application architecture (you’ll recognize these in a contemporary fashion as a SPA or PWA) onto the most successful hypermedia system of all human existence.

Google deserves a good portion of the blame for this sacrilege. While succeeding with Android as an alternative to iOS, they failed to create a culturally relevant alternative to iOS. They struck out on a mission to create a modern competing platform — the progressive web application, or PWA. PWAs seek to essentially recreate the functionality of a native mobile app environment inside of the browser, including features to make web applications available offline and access hardware (camera, sensors).

Idealist developers who thought that Apple's "walled garden" approach to software distribution was misguided (if not harmful), and web developers who had little interest in learning a native SDK, embraced PWAs.

Today, we observe the web heading toward a far cry from what it was originally envisioned as. In the process, we’re erasing the best attributes of that very hypermedia system, and it would appear that many developers don’t know the difference or care to understand.

To put it another way, the most successful hypermedia system of all time has been reduced to a facsimile of Microsoft’s “Click-Once” deployment technique. How the tables turn.

I Reject This

In my professional experience, the explosion of ReactJS and later, NextJS, has resulted in bloated web applications, an introduction of hard problems into what was once a very simple and accessible platform, duplicated logic between client and server, and often requiring reimplementing facilities of what established back-end frameworks (Django, Rails) have long shipped with (pagination, form validation).

We’re writing all sorts of front-end code that we simply do not need to write, except to appease budding junior developers who teethed on NextJS.

Web projects take longer than they should, and have classes of issues that are tedious to address when using things like React, issues that often handled in the most bog-standard of ways by established server-side frameworks.

And hey, ReactJS is an easy, winning career technology stack to put yourself in. Even as a self-proclaimed “hater,” I begrudgingly shipped React/NextJS code for years at Vimeo for a nice paycheck.

The Tidelas Project

I created my premier website, Tidelas, first using Django and VueJS, then later Django and HTMX, before lifting the entire site and porting it to live on top of Umbraco with HTMX.

The Django and HTMX combination was glorious. I was able to implement so many wonderful features very quickly and easily, and felt like I was running circles around myself and my team at Vimeo.

I later realized that I did not like the editing experience of Django admin for such a content-heavy website, so I ported the entire project to Umbraco, and I brought HTMX along for the ride.

In the forthcoming, follow-up article, I'll show you how I was able to mix HTMX into Umbraco for a best of both worlds architecture.