Static Server Side Rendering + hydration with Preact WMR, zero Twind runtime in production builds

[danielweck]

Hello!

First of all: huge thanks to the Twind project(s) maintainers! The feature-set is great, the API is very flexible, and the performance is pretty good too :)
I hope that the community will grow!

To the point: I managed to negate the need for the Twind runtime entirely in my small frontend project (nothing too complex at the moment, just a set of statically-generated web pages, with some lazy-loaded routes / dynamically-imported components).

I think that some of the techniques I used may be of interest to other developers, so I am planning on documenting things. Right now my code is not in a presentable state. This is a spare time project so I cannot give an ETA.

I find that Twind is a good match for Preact WMR, in the sense that the performance of the Twind runtime (instant Tailwind CSS generation!) is compelling in a development environment where Hot Module Reload / Fast Refresh is near-instant, even with a TypeScript codebase.

In production builds, Preact WMR generates a static fileset for each individual route (including lazy-loaded routes / dynamic module imports). Although Twind can be used for static Server Side Rendering (see the various "use with Twind" Preact / WMR / Next / "render-to-string" integrations), I my project I really wanted to eliminate the need for the Twind runtime during hydration. I realise that this may be seen as a "micro optimisation", but every byte counts in the overall user experience (especially on mobile devices over poor network connections).

I am not just talking about Twind's combined Javascript/CSS bundle size (+plugins), but also about reducing the computational costs incurred during page hydration: behind the scenes, Twind must parse every CSS class token, check duplicates, sort styling rules / order for selector precedence, update the stylesheet / CSSOM, etc. In my usage scenario, this performance penalty (however small) is not justified, as the pre-rendered documents are already populated with all the necessary styles.

In my admittedly-limited use case, the CSS runtime is not only redundant at hydration stage, it is also unnecessary during subsequent user interactions (i.e. not just "hover" / "focus" states, but also mutations of the class props in the virtual DOM which occur when the application state changes, causing re-renders). In my scenario, the "critical" CSS bundle shipped in pre-rendered webpages is not just for "above the fold", it covers the entire Single Page Application that comes to life after the initial hydration of a pre-rendered document (well, obviously this excludes dynamic routes / lazy-loaded components which may import their own styles after the initial content render).

So, in my next post(s) I will try to articulate some technical / architectural details, but first I must give my source code a good cleanup, so I can share code snippets. Final note: this is just an experiment at this stage, but I am probably going to use a similar project structure to quickly scaffold other small front end projects.

[danielweck]

I am not using Twind's off-the-shelf Preact and WMR "use with" packages, but the technical underpinnings are identical:

• https://github.com/tw-in-js/use-twind-with/tree/main/packages/preact
• https://github.com/tw-in-js/use-twind-with/tree/main/packages/wmr

[danielweck]

I use the standard / official Preact WMR package, which provides sufficient hooks into the build system to inject Twind's "style extraction" mechanics:

• https://github.com/preactjs/wmr/

[danielweck]

An update before I sign off for the day:

The goal of my Preact WMR experiment is to remove the need for the Twind runtime on the client side in production builds. This requires that each statically pre-rendered HTML page contains the cumulated sum of all "possible" Twind-generated classes / styles, by which I mean: not just the CSS used by the page itself (i.e. on first render, as well as post-hydration user interaction / local state updates), but also the CSS potentially needed when navigating to another page handled by the client-side router (i.e. the point at which the website effectively becomes a Single Page Application).

Side note: async lazy-loaded routes may in fact be designed to fetch their own styles "on the fly" (i.e. CSS computed ahead of time via static SSR, instantiated on the client as needed) ... but let's ignore this architectural case for now.

In my original implementation, the aggregated Twind CSS was serialized into the <style id="__twind"> ... </style> tag of each HTML page, and it contained: Twind preflight styles, page-specific styles, and "other pages" styles (i.e. other routes). On a positive side, Tailwind's "utility classes" are typically reused by many components via common CSS selectors (thus why not many CSS rules end up being duplicated in the aggregated build), but on a negative side, heavy use of apply() or style() to "componentize" the generated CSS does results in some degree of CSS rules redundancy.

Quick note about the order of CSS selectors in Twind's aggregated stylesheet: this is mostly dictated by Twind in the stylesheet generated for the current page. However, merged additions are not necessarily inserted according to Twind's prescribed order, which in principle could be problematic. However in practice this is safe thanks to CSS selector specificity.

Now, in my improved implementation, the "critical" CSS is generated separately from the "rest", for each individual routed page. On the client side, the "critical" CSS is loaded immediately with the document markup (it is a blocking operation, the <style id="__twind"> element is in the HTML head), whereas the "rest" is deferred in time for hydration, using this simple technique:

<link rel="preload" href="./twind.css" as="style" onload="this.onload=null;this.rel='stylesheet'">
<noscript><link rel="stylesheet" href="./twind.css"></noscript>

Overall I am quite satisfied with this approach, and I think that the gains justify the tradeoffs (in my usage scenario, anyway). The main constraint is that JSX class and className props must be used in a specific manner, in addition to a few ad-hoc props which I created to handle Twind's css(), apply() and style(). Placing these directives in the JSX component tree means that a special Preact VNode hook can be used in WMR's dev mode and during WMR's pre-rendering pass, to populate Twind's stylesheet. In the production code bundle, the VNode hook is pretty much a no-op, as there is no Twind runtime.

The other downside is that the build process is quite convoluted, as this involves invoking Twind as part of WMR's build process, to be precise whilst pre-processing source files. I will provide further details when I release code + documentation, but in a nutshell: the TSX/JSX files are statically analysed to transform Twind expressions ahead of time to a simple object structure that exposes the raw Tailwind CSS classes (e.g. Twind's group syntax is expanded). In fact, I must make sure this approach works with Twind's recent introduction of "dynamic" classnames.

Sorry for all the talking and the lack of code ... I promise I will release actual source code, when it's ready :)

[danielweck]

I'm using esbuild to bundle the config to include all dependencies like plugins in the bundle.

Ah yes, I should have explained further:

I use Sucrase as a Rollup plugin to "bundle" an executable version of the Twind config (including preflight, plugins, etc.), and in the NodeJS runtime of my WMR Twind plugin I eval the actual config to be passed to Twind's setup(). Something like that:

const twindConfig = await eval('(x => import(x))')(tempFileUrl);
setup({ ...twindConfig, sheet: asyncVirtualSheet });

...where tempFileUrl is the output from Rollup + Sucrase.

In cases where the Twind config is plain JavaScript instead of TypeScript, I can bypass the Rollup-Sucrase transpiling, of course.

[sastan]

I see. That does achieve the same thing. That may be a good option once I'll start to make the typescript-plugin work in the browser (hint: twind playground).

[danielweck]

The style() handler is the trickiest one because it generates ahead-of-time all possible styling variants (in order to eliminate the need for Twind runtime in production builds), and the results are stored / injected in VNode props.

My WMR+Twind hydration model currently "works fine" and I would happily continue to use it in my little experiment, but it is not easily scalable / generalizable. I want to improve this.

The fundamental idea (as currently implemented) is to introduce a Preact Context (and associated Provider) near the root of the app's component tree. The Context's Provider value is a simple object with a "getter" that returns the Twind style() variants (which can then be consumed by Preact components further down the tree, with a useContext() hook), for both "development" and "production" cases (i.e. either generated just-in-time by the Twind runtime during regular Preact render, or pre-computed ahead-of-time during Preact WMR's prerender build, and later picked-up by Preact's hydrate).

What I dislike the most about my current implementation is that depending on mode "development" (initial render + multiple hot reload / fast refresh) vs. "production" (initial DOM + single hydrate), the aforementioned Context.Provider's object "getter" either has instant access to VNode props (DOM not rendered yet), or deferred / lazy access via rendered DOM attributes. I will do more research into Preact's component tree lifecycle, but right now I think this is a necessary architectural constraint that yields somewhat "spaghetti" code difficult to abstract.

A final note on the particular point of Twind style(): in my experiment, each possible variant is pre-computed and injected into the Preact component tree as additional props and DOM attributes. I use the data- attribute naming convention, because it is ideal for rapid prototyping (no TypeScript checks), and most importantly because of extensibility (e.g. data-tw-style-button-default, data-tw-style-button-active-and-pressed). I do actually have a typing layer on top of this (I hate using any!), but once again I would like to make this more scalable / generalizable.

[sastan]

I'm planning to extend the return values of style to include all variants and the matched combinators. Maybe that could help?

I would be very interested in looking into what you have achieved and what you are missing/struggling with.

[danielweck]

I'm planning to extend the return values of style to include all variants and the matched combinators. Maybe that could help?

I am not sure I understand what you mean.

Right now my declarative model includes the object passed to style(), as well as a separate object which is used to instantiate all concrete Twind variants potentially used in my app (see the button() arguments in the doc example: https://twind.dev/docs/modules/twind_style.html ).

[danielweck]

I haven't mentioned actual numbers yet: right now the bytes economy in the resulting frontend is circa 60 KB of statically-minified, but uncompressed code (I mean, HTTP gzip compression).

This size saving corresponds to Twind's default runtime plus the Typography and Form plugins, in my case (I will no doubt add plugins to my Twind configuration as my design needs evolve).

This may not seem much relative to other bundle / resource sizes, but in my case this is worth the effort :)
(also, no Twind runtime means no additional computational costs during hydration, as I mentioned in my original post)

[danielweck]

Thought of the day: the proposed support for style() as plugins (see #159 (comment) ) would yield further byte savings in my performance-oriented project, as any Twind "directive" included in setup() is by definition nullified (thanks to tree shaking) in production builds where the Twind runtime is erased entirely.

This is possible thanks to the declarative / static nature of "most" Twind constructs, which makes it possible to compute ahead-of-time the class/rules mappings (i.e. to populate critical + deferred stylesheets, and to implement hydration mechanics that do not rely on Twind to resolve classnames). I said "most" Twind constructs because the [] square bracket syntax (i.e. truly dynamic classnames) is obviously antinomic with my design goals here, and is therefore clearly out of scope.

So, I am now considering migrating further Twind constructs to setup(), most notably css() which in my code instantiates :global styles, using apply() to leverage TailwindCSS utility classes, but with higher-specificity selectors such as :root#twind > body > div.preact-app ... to win the cascade game (i.e. style overrides such as accessible keyboard focus outline applied consistently in every UI component).

[sastan]

I'm really interested in what you are doing there – I want to have a twind zero runtime one day.

[danielweck]

I look forward to sharing some code, for you guys to review / improve. I think it would make a good "recipe" for Preact WMR, probably applicable to other static SSR frameworks as well.

[danielweck]

The Twind runtime (including style, css, and style-vendorizer) weighs in at 18KB Brotli-compressed (just over 20KB with GZip).
This doesn't include any plugins, so in my case there is an extra 3.4KB (Brotli) for forms and typography.

Like I said before, I think this is a perfectly acceptable payload and runtime cost to pay, given Twind's feature set. Plus, there are build options to generate stylesheets ahead of time (e.g. extraction of "critical-ish" CSS using Twind CLI), so that Twind's just-in-time CSS generation can be deferred without causing FOUC (Flash Of Unstyled Content).

NOTE: the treemap visualization is misleading here, in that Twind appears proportionally huge in the vendor space, when really it is my project that is tiny (i.e. not representative of a a real-world production website). That being said, based on experience from previous projects, eventually I don't envision this particular one to include large JS dependencies, so Twind would probably remain one of the larger chunks, relatively speaking (this is a moot point in my case, as this Rollup chunk is only used for static SSR, it is not loaded in the front end on the client side, at all).

[rschristian]

Just popping in to say that rollup-plugin-visualizer (which we use in WMR to create this view) added a white/blacklist for resources, and soon, will allow us to set defaults for those values. That should help give a better picture of what ends up being in the client side bundle.

[danielweck]

Thanks for the "heads up". I have been following the WMR activity white closely, and I look forward to these improvements.

[danielweck]

Interesting and fun development. Out of curiosity, I wanted to implement some type of "island architecture" in this Preact WMR experiment. I managed to make this work using a hybrid approach.

Reminder of my primary design goals: static SSR resulting in zero Twind runtime on the client side, and crucially: non-overlapping separation between critical CSS used for dry render (for each SSR-discovered route), vs. lazy-loaded styles for post-hydration use (i.e. SPA runtime).

The technique is a bit "hacky", but it seems to work reliably: I use preact/compat Suspense + lazy() for the dynamically-loaded content "islands". There is no React at all in my pure-Preact little app, but the "compat" package which is normally used to support React components includes a self-contained Suspense implementation which works just fine in isolation. Crucially, I use this in combination with WMR's isomorphic Router + lazy() + ErrorBoundary (which is effectively a container high-up in the component tree that captures the thrown exceptions linked to the lifecycle of suspended descendants).

At first I assumed that mixing two "lazy" techniques inside the same component tree would be problematic, but after reading the source code of both and running some tests, I actually think it is safe thanks to the "suspend boundaries" that intercept thrown exceptions and orchestrate re-renders.

Lazy-loaded "islands" of content can be loaded manually by the user (e.g. an "expand" button as part of an HTML details / summary element), or automatically during scroll (e.g. Intersection Observer). The effect on the client side is pretty effective, performance-wise and in terms of user experience. I checked that lazy routes can contain lazy component islands too (and subsequent renders are instantaneous). All good.

I suppose this can be called "progressive / partial hydration"?

The tricky part was to make sure that the lazy component "islands" are SSR'ed just like lazy routes (i.e. code split for optimal bundle fragmentation and network caching), with their own Tailwind stylesheet rules excluded from the critical CSS.

To achieve this, I implemented the same hack used for the 404 page, which isn't explicitly linked from the navigation header (obviously), but which still needs to be discovered by the WMR SSR build process, otherwise the "not found" page doesn't have its critical CSS "extracted" (well, there is no static "extraction" / parsing, but rather an actual render pass that precisely determines the Twind-generated stylesheet). The trick is simple: display: none HTML links that get picked-up by the SSR builder but remain totally innocuous / non-interfering at render time.

I am not open-sourcing my code yet because there are several key moving pieces at the moment. Notably, the logic behind WMR's isomorphic router/lazy is likely to change. My code is a real mess based on a locally-built branch of WMR.

Quite a few references, if you're curious :)

preactjs/wmr#530

preactjs/wmr#535

preactjs/wmr#425

---

preactjs/wmr#429

preactjs/wmr#431

---

preactjs/wmr#525

preactjs/wmr#504

preactjs/wmr#364

preactjs/wmr#358

---

preactjs/wmr#170

preactjs/wmr#169

[danielweck]

I should also point out that preact-ssr-prepass is not used in WMR, and nor do I use it in my experimental app. During the SSR build process, WMR does of course invoke renderToString() and awaits suspended routes / lazy components. Because I "register" the Suspense/Lazy islands via the Router, I achieve both static pre-rendering of async components, and their dynamic fetch / resolution at runtime. To be honest, I am not 100% sure that the Preact VNode internals (DOM reconciliation at hydration stage) is bullet proof when mixing the two different lazy() flavours ... but I am not noticing any bugs so far :D

[danielweck]

If you are reading this thread in the future, starting from the top, then note these more recent additional notes (further down in this thread). Link: #147 (comment)

[danielweck]

I finally managed to distil my Preact WMR web app (the one with zero-runtime Twind) to a bare minimum that I am happy to share with the community. Here is a repository with some code, a demo, and even some documentation! :)
https://github.com/danielweck/preact-wmr-twind-zero/blob/main/README.md
I will migrate this to Twind v1 soon, before I start porting the more sophisticated features from my other web app (notably: support for Twind variants, dynamic class names, global CSS, Twind plugins, themes, etc.).

[danielweck]

I migrated my small demo to Twind v1.
Thanks @sastan for the amazing work 👍

I improved the README that describes the techniques used to achieve my "zero runtime" design goals:
https://github.com/danielweck/preact-wmr-twind-zero/blob/main/README.md

I posted the following screen capture which illustrates one of the main benefits of zero-runtime Twind ... yes, I know, this gives a grossly exaggerated impression due to the relative size of dependencies :)

My Twind SSR/SSG demo will intentionally remain super small (much like a reduced test case), and right now it only includes basic tw() and shortcut() calls. I will gradually port and cleanup my pre-V1 code (there are many Preact WMR-specific hacks and bug workarounds, which would cause unnecessary noise in this Twind demo).

[danielweck]

Here is a super-reduced network waterfall report and performance flamechart that illustrate the principle of parallelised fetch of JS and secondary CSS (immediately after the initial fetch and parse of the HTML + inline critical styles). Note the relative timing of web vitals:

[danielweck]

@sastan I hope you don't mind, I juxtaposed the Twind logo and the Preact WMR logo at the top of my README:
https://github.com/danielweck/preact-wmr-twind-zero/blob/main/README.md
Please let me know if you are okay with this :)
(it's just for fun, I am happy to remove the offending image if necessary)

Also, I felt I initially didn't do a good-enough job at explaining my rationale for wanting to eliminate Twind's runtime from the client-side Javascript bundle. Twind is plenty lightweight and performant, so I didn't want to give the wrong impressions. I updated my README to better articulate my motivations.

Cheers 👍

[sastan]

I'm very happy with everything you did! Great job. Sadly, I didn't have the time to look into it. But I will!

[danielweck]

Incremental update: in my old (private) demo, I was using preact/compat's Suspense and lazy() API to demonstrate the segregation of Twind "critical" (dry render styling) vs. "secondary" styles (hydrated SPA) at the async component level, in addition to sync/async mutually-exclusive routes.

I wasn't feeling comfortable (because of under-the-hood, potentially-conflicting Preact options.vnode hooks) about cherry-picking this preact/compat code (normally used for lazy components) and mixing it with Preact WMR's own ErrorBoundary + lazy() (normally used for async routing).

Note that although based on the same principle of "thrown Promise exception", preact/compat's Suspense implements the fallback prop to display a placeholder "loading" component, whereas Preact WMR's solution preserves the current route until the incoming route arrives (in fact, in my previous demo I manually implemented the "loading" state, which was an interesting exercise due to router events quirks).

So, in this new (public) demo, I am now using only Preact WMR's ErrorBoundary and lazy() to code-split async components (not just routes) and to displace their computed Twind styles from the instant "critical" stylesheet (which applies to the current pre-rendered route) into the deferred "secondary" stylesheet (which applies to subsequent dynamic renders). In my demo the lazy component simulates a 1s network fetch delay (just like the async route, actually), and I also chose to reveal it upon user interaction (button press). In other words, the dry-rendered static HTML doesn't contain the lazy component, but the hydrated page allows the user to dynamically trigger external code bundle fetching. At that point, the Twind styles specific to the dynamic component are already available from the "secondary" stylesheet, so there is no FOUC (Flash Of Unstyled Content). Naturally, this approach works well even with async components that mount near-instantly, without user interaction (I might add this in the demo to illustrate).

The fact that I am not using preact/compat's Suspense and lazy() means that there is no "loading" placeholder in the UX, but I am happy with this caveat in the context of this minimal demo. I would rather keep the demo as simple as possible, so that the emphasis remains on: integrating Twind as "zero runtime", with support for "critical" stylesheet for each pre-rendered route, accounting for async/lazy component styles in order to minimise the initial dry-render load.

More info in the README:

https://github.com/danielweck/preact-wmr-twind-zero/blob/main/README.md

(notably, an explanation of the "sub router" trick used to separate async lazy components styles from the "critical" stylesheet ... it is quite a hack, but it makes sense when you think about it with your head twisted backwards and up-side-down ;)

[danielweck]

Project update: I have just integrated the new Rust-written ParcelCSS minifier / optimiser ( https://github.com/parcel-bundler/parcel-css )

Twind already generates "optimised" CSS code, so in principle the gains should be quite minimal. However in practice (well, in my project anyway) the build pipeline generates "critical" and "secondary" stylesheets resulting from the CSS code produced by a variety of Twind constructs: tw, shortcut, etc. but more notably preflight and css which can consume arbitrary CSS code, not based purely on reusable utility classes.

ParcelCSS includes sophisticated heuristics to shrink CSS code, such as identifying redundant / duplicate selectors ... which exist in my sample project due to using a preflight and css "reset" strategy on the @layer base slice of the styles cascade.

So I am seeing some appreciable size reduction, mostly in the "critical" inline CSS stylesheet (i.e. the one that's embedded in the static HTML route), as the preflight (or my css "reset" equivalent) is common to all routes. As anticipated, I am not seeing significant savings in the "secondary" stylesheet.

Source code reference: https://github.com/danielweck/preact-wmr-twind-zero/blob/main/wmr-post-prerender-twind.mjs

[danielweck]

Hello :)

In addition to using Twind runtime only server-side (or more precisely, at build time during whole-site SSG), I am now also using a technique to (1) avoid unnecessary client-side hydration of "static" markup islands, whilst preserving hydration consistency (no potential mismatch), and (2) avoid shipping the compiled hydrator code which effectively duplicates the markup that's already rendered in the HTML. Technique (1) prevents wasting compute cycles and consuming memory / increasing garbage collection. Technique (2) minimises network load at the critical initial render stage.

Crucially, Twind classes and corresponding critical + secondary stylesheets must be generated without fail. As the no-hydration strategy applies to the client side only (where Twind is not executed anyway) this approach works out of the box in my project:
https://github.com/danielweck/preact-wmr-twind-zero

If you're interested, I am copying the relevant section from the README here (in a nutshell: I use lazy-loaded / async import'ed components to selectively fetch from the network only during route navigation in SPA mode, in combination with a neat Preact trick that skips subtree hydration without causing hydration mismatch):

"Static" content islands

PreactWMR prerendered builds perform ahead-of-time SSG, and in this project there is no live SSR. HTML markup is generated either at build time (on the "server", so to speak), or by the web browser client during hydration, at which point some Javascript code effectively duplicates the information already encoded in the HTML source, but injects event handlers, etc. In cases where the content is "static" (i.e. frozen HTML islands not affected by dynamic variables or user interaction, as regular components typically are), the duplicated component tree in the Javascript bundle causes unnecessary network load, in addition to wasting compute cycles, and also consuming more memory / increasing garbage collection (at hydration time).

To work around this problem, here we use a neat Preact trick that prevents a component subtree from being hydrated, whilst maintaining hydration consistency (i.e. no potential mismatch). See source code for technical details (search for NO_HYDRATE). From the developer point of view, we simply mark some pre-rendered HTML islands as "static" / self-sufficient (at least, for pre-SPA first-render ... more on this below).

Next, we implement a technique to avoid shipping compiled JSX to the client unnecessarily. We wrap a lazy component / async import inside a fragment that conditionally renders NO_HYDRATE. The web browser totally ignores the external Javascript bundle during hydration, thereby minimising network use at the crucial initial render stages.

Naturally, once the web app becomes a SPA (immediately after hydration), route navigation can occurs and consequently any such static HTML island needs to be reconstructed into the live HTML document. In other words, the corresponding lazy-loaded / async-import'ed component must be fetched (or obtained from local cache), and rendered. This is standard Preact WMR stuff, no additional hack is required for this to work. We just use a conditional to determine exactly when a component must render NO_HYDRATE (combination of "document has hydrated" and "component has rendered at least once").

Just for fun, this project also implements the edge-case of embedding / nesting static content islands inside lazy-loaded components. As expected, NO_HYDRATE is non-sensical in this context and is never invoked, given that no static HTML was delivered in the first place. Once inside the context of a dynamic import, there is no pre-rendered HTML (unless of course the markup island itself is individually SSG'ed, but then the DocumentFragment would need to be spliced into the current document which introduces unnecessary complexity ... we might as well just let Preact do the rendering).