Web Components + HTMX: A Lean Architecture for Content Sites That Ship

Every front-end framework promises better developer experience. Few of them promise lower total cost of ownership. When I rebuilt this site, I optimized for the second thing - because for a small operation shipping content, the real costs aren't in writing components. They're in maintaining them 18 months later when the framework has moved on.

The stack I landed on is Custom Elements (the browser-native kind) plus HTMX for routing. The site weighs about 35KB of JavaScript total, feels like a single-page app, and runs on infrastructure that costs nothing. If you want the philosophy behind that JavaScript budget, I unpack it in The Minimal JavaScript Approach.

This article covers the architecture and - more importantly - why these choices make business sense.

Why I'm not using a framework (and why that's a business decision)

The typical framework pitch is better DX, faster iteration, larger hiring pool. Those are real benefits - for teams of 5+ shipping complex applications. For a solo operator or small team running a content site, the calculus is different:

1. Maintenance cost. React, Vue, Svelte, and their ecosystems ship breaking changes regularly. Each major version bump is an unpaid project. Custom Elements use browser APIs that have been stable since 2018. The maintenance burden is near zero.
2. Dependency surface. Every npm install is a supply chain risk. My components compile to plain ES modules with zero runtime dependencies. The only third-party script is HTMX itself (14KB minified).
3. Bundle size as a business metric. Every kilobyte of JavaScript is a tax on mobile readers. At 35KB total, this site loads faster than most analytics snippets. That directly affects bounce rate, time-on-site, and SEO rankings.
4. Portability. If I need to embed these components in a client project, a microsite, or a different hosting platform, they just work. No build pipeline required, no framework version to match.

None of this means frameworks are wrong. They're excellent tools for the problems they solve. But for a content site that needs to stay fast and cheap to maintain, they're solving problems I don't have.

HTMX as the routing layer

HTMX gives me SPA-like navigation without owning router state or hydration logic. For a deeper dive on how HTMX fits into progressive enhancement, see HTMX and Progressive Enhancement.

Here's what it does in practice:

• Article cards use hx-get="/article/{slug}/fragment.html" and hx-push-url so every navigation updates browser history and produces a shareable URL.
• Fragments (fragment.html) contain just article markup. Full pages (index.html) include the <primary-layout> shell for first-load SEO.
• Out-of-band swaps (hx-swap-oob) refresh recommendation slots on both desktop and mobile without additional JavaScript.
• HTMX lifecycle events (htmx:beforeRequest, htmx:afterSwap) power the loading indicator and scroll management inside PrimaryLayout.

The result feels like a SPA to readers - instant navigations, no full-page reloads, back button works correctly - while remaining fully server-rendered for crawlers and first-time visitors.

PrimaryLayout: encapsulation that pays for itself

PrimaryLayout is a Custom Element that owns the entire page shell: header, nav, main content area, and recommendation slots. It uses shadow DOM for style isolation, which means I can evolve its CSS without worrying about collisions with article content.

Key responsibilities:

• Fixed header management. Spacers inside the shadow DOM push content below the header. Change the header height once, and every page adapts automatically.
• Safe-area insets. CSS env(safe-area-inset-bottom) ensures buttons never hide behind phone navigation bars - a detail that's invisible in desktop testing and critical on mobile.
• Loading feedback. A progress bar pulses under the header during HTMX navigations and fades out on swap completion. No skeleton screens, no spinners, just a subtle cue that the site is working.
• Scroll management. scrollMainToTop() resets the viewport after each navigation so readers always start at the top of the new article.

The deeper UX decisions behind this component are in Mobile-First Layout That Ships.

The architecture pattern here is straightforward: let the layout component own DOM shape and encapsulated styles, while thin global event listeners (registered once per document) coordinate HTMX behaviors. That preserves shadow-DOM isolation without creating a Byzantine event system.

Static generation: two renders per article

The build script renders each article twice:

1. Fragment - just the article content, served to HTMX for client-side navigation.
2. Full page - the complete <primary-layout> shell with slotted content, served for first loads and SEO.

Slots (pl-content, pl-aside, pl-mobile-recs) are populated at build time, so the first byte already includes recommended articles. After navigation, HTMX swaps inject updated recommendation markup out-of-band, ensuring the sidebar never shows the article you're currently reading.

Because everything compiles to deterministic HTML and ES modules, Netlify caches aggressively at the CDN edge. No origin compute, no cold starts, no database connections. For the full case for static site generation as a business decision, I wrote a separate piece.

Operational benefits (the ones that save money)

• Debuggability. When something breaks, I read the generated HTML and JavaScript directly. No source maps to hunt down, no framework abstractions between me and the bug. Incident response is fast.
• Portability. The components are standard ES modules. If I migrate hosts, embed cards in an external site, or hand the codebase to a contractor, there's nothing proprietary to explain.
• Hiring flexibility. Anyone who knows HTML, CSS, and JavaScript can contribute. There's no component DSL, no state management library, no build toolchain to learn. For a small team, that's a real advantage.
• Zero infrastructure ops. No servers to patch, no containers to manage, no databases to back up. The site is a folder of static files on a CDN. Uptime is Netlify's problem, not mine.

The tradeoffs (because there are always tradeoffs)

This architecture is not the right choice for every project. If you're building a complex web application with rich client-side state - a dashboard, an editor, a real-time collaboration tool - you'll likely want a framework. The React and Vue ecosystems exist for good reasons.

But for content sites, marketing pages, documentation portals, and similar properties where the primary job is displaying information fast, this stack hits a sweet spot: app-like UX, minimal maintenance, zero hosting cost, and a codebase that any web developer can read on day one.

The bottom line

The combination of native Custom Elements, HTMX, and static generation is not about purity or minimalism. It's about choosing the right level of complexity for the problem. A content site doesn't need a framework runtime, a hydration step, or a build pipeline that takes 45 seconds. It needs fast pages, good SEO, low maintenance, and a codebase you can hand off without a two-week onboarding.

If you're running a content property and tired of framework upgrade cycles, this is a low-risk path: start with custom elements for layout, layer in HTMX for navigation, pre-render everything at build time, and ship. The result is a site that stays fast, stays cheap, and stays understandable - which is all a small business really needs from its front end.