Using Preact with Docusaurus

[SethFalco]

Hey hey!

I'm having some trouble, so I was wondering if anyone more involved in the project may have some insight.

I maintain SVGO.dev, a small website generated with Docusaurus (an SSG), and I'd like to migrate it from React to Preact.

Unfortunately, by adopting Preact, I seem to have broken SSR. After following the Switching to Preact guide, the production build works and produces the JAMstack friendly output, but it outputs a CSR application which doesn't work at all without JavaScript enabled.

(Normally, building a Docusaurus site builds the website with SSR, and outputs the built HTML with a lighter JS bundle to hydrate interactivity. The bulk of the website works even if JavaScript is disabled.)

I have read Server-Side Rendering in your documentation, and can see you have a dedicated package for it, but not any kind of alias. Does this mean Docusaurus would either have to have explicit support for Preact SSR, or that I'd need to write a Yarn patch? Or is there a way to already retrofit this behavior that I'm just missing?

I was confused here because there are no errors/warnings at all. If anyone could provide guidance or a good starting point at what to look for based on the symptoms described, that'd be appreciated!

My branch so far for svg/svgo.dev with the migration to Preact:
svg/svgo.dev@7343911

Thanks, and no pressure if there's limited support available. I understand you can't know about every framework out there. 👍

[rschristian]

Will take a look shortly, but preact/compat does have a /server entry (i.e., preact/compat/server) that just imports & re-exports from RTS to maintain compatibility, so all should be good there:

preact/compat/server.mjs

Line 1 in 2d6811d

import { renderToString } from 'preact-render-to-string';

preact/package.json

Line 80 in 2d6811d

"./compat/server": {

[SethFalco]

Ahh, thanks for sharing that! (And I appreciate you sparing time to look at this!)

I did grep in Docusaurus for renderToString but got no meaningful results. Seems I should've grepped for react-dom/server.

Looks like this is where Docusaurus renders the app, I can also confirm this is invoked many times at the end of the build too:
https://github.com/facebook/docusaurus/blob/v3.8.1/packages/docusaurus/src/client/renderToHtml.tsx#L18

Which renderToPipeableStream is indeed exported from preact/compat/server. I'm still not sure what's wrong, but will continue to look at this once I finish some client work.

[rschristian]

Do you have a branch I can checkout? The commit you've linked above is seemingly orphaned.

[rschristian]

Alrightly, after a bunch of blind fiddling I seem to have gotten it working. I avoid dealing with Yarn, so can't really submit a patch as it wouldn't address the lockfile, but once you've gotten react fully out of node_modules, you should just need to comment out line 183 of node_modules/react-loadable/lib/index.js -- no idea why that fails, or why that module is even needed today, but builds do seem to work once that's corrected.

[SethFalco]

Do you have a branch I can checkout? The commit you've linked above is seemingly orphaned.

Ah, sorry! That's because the branch was on my fork rather than in the main repository. Despite being a maintainer, I still tend to work from a fork instead.

This was the branch, though I guess it's of less importance now:

• https://github.com/SethFalco/svgo.dev/tree/preact
• chore: use preact instead of react svg/svgo.dev#37

no idea why that fails, or why that module is even needed today, but builds do seem to work once that's corrected.

It works! Thank you very much for the guidance. I'll post about this in the discussions section of Docusaurus too. Maybe they'll have some insight on what's going on there and be able to smooth out the process for users in future.

I'm not very familiar with Preact but it's definitively something we'd like to support

— facebook/docusaurus#4211 - Sébastien Lorber @ 2021

Meanwhile, impact for SVGO.dev:

	Before (React)	After (Preact)
Landing page (uncompressed resources)	997.98 kB	840.35 kB
First page of docs (uncompressed resources)	1.50 MB	1.34 MB

[rschristian]

Sorry I couldn't be of more help, and perhaps there's a better solution someone could point you to. I almost wonder if it's a dual-package hazard issue but nothing else seemed to fall apart which is weird. Not sure what would break that context like that.

Can't speak much to the React side of things, but in Preact, there's really no need for anything like loadable these days to my understanding. We've supported async rendering & resolving promises server side for years now, even prior to streaming support.

[slorber]

Docusaurus is a static site generator, and we don't use streaming SSR but render everything ahead of time (unless the user opts out).

We historically use React-Loadable as a way to collect all the loaded modules being rendered during SSG, so that we can then inline all the required JS chunks in the static HTML pages. There's probably a way to get rid of that library, but for now, this is what we use.

It's great if Preact can work for Docusaurus today. In the future, we plan to support React Server Components running at build time (facebook/docusaurus#9089), so I wonder if we'll be able to keep supporting Preact, and if the 2 RSC implementations are similar enough for them to be swappable.

We also plan to leverage features such as <Activity>

[rschristian]

Docusaurus is a static site generator, and we don't use streaming SSR but render everything ahead of time (unless the user opts out).

? You do use the streaming methods (renderToPipeableStream, linked above), likely as React otherwise doesn't support suspense boundaries server-side to my knowledge. You can stream to static HTML, streams don't inherently mean per-request renders (usually referred to as "SSR").

React's prerender function is similarly built upon streams, despite it meant for ahead of time use. Wonky API(s), IMO.

and if the 2 RSC implementations are similar enough for them to be swappable.

There will not be a Preact RSC impl, at least not from us.