✨ Upgrade to Remix 2 [Spike]

[agoose77]

This PR is a spike to see whether we can upgrade to Remix 2, timeboxed to three days.
I will spend a few days (3) maximum in this direction before evaluating whether this can be made into a prototype or we need to rethink e.g using Next.js' static exports feature.

Context

We are currently pinned on an old version of Remix due to an infinite-reload bug for static exports. We cannot upgrade without breaking static exports (required for RTD, GitHub pages).

[agoose77]

As per usual, this is much harder than it should be because of weird dependency graphs and poor module support.

It looks like @remix-run/dev@^2.9.2 pulls in vite@^4.0.0 instead of 5.0.0, which conflicts with our requested version. I somehow fixed it temporarily, but it resolves to this solution.

Before this problem, I was struggling to deal with react-syntax-highlighting, which seems to be picked up as a CJS dependency despite the imports using the ESM entry

[agoose77]

OK, hacking around that by dropping syntax highlighting and overriding the vite version. Now it loads a page, but complains about mixing server and client code

[agoose77]

OK, at this point myst-theme mostly works; I ripped out syntax highlighting (and probably broke some other things).

Findings

SPA Mode

The code that introduced the reload behaviour has since been modified to support Remix V2's SPA mode. If we wanted to upgrade Remix, we could do so iff. we found a way to use SPA mode to generate our static exports. Generating an SPA is a useful output for MyST, but it is not the best-case scenario for static exports; client-side SPAs introduce the "white-flash" loading screen, and have a long-time to meaningful first paint.

SSR-SPA

However, underpinning Remix 2's SPA mode is the clientLoader mechanism. It looks like the clientLoader can be used to build an SSR-SPA.¹. This would be an improvement over our existing SSR MPA, because we could perform link-prefetching (and other goodies!). I assume given the existence of this repo, the problem associated with #184 does not cause issues, but I don't have enough of the context to be certain.

Vite

Another benefit of this upgrade, though, is that Remix now intends to use Vite for the server (faster, more plugins, etc).

Footnotes

1. A server-side-rendered single-page-application - each route has a dedicated HTML page, but once that page loads, navigation between pages is performed as an SPA (not loading HTML!) This is faster and supports fun optimistions. ↩

[agoose77]

@rowanc1 / @stevejpurves do you recall #184 well enough to know whether the approach taken in https://github.com/brophdawg11/remix-ssg/tree/main/demos/ssg-spa-client-loaders would work?

The reloading logic in Remix 2.9.2 is https://github.com/remix-run/remix/blob/ff06e1656108bc21244e1fd4b33ed53e22b85158/packages/remix-react/browser.tsx#L205-L217

My initial thought is - the bug is still there if we take our existing approach, so I am guessing perhaps not. I am only guessing, though; I have no understanding of why the Remix context wouldn't match the true URL.

[choldgraf]

Given that this is a pretty complex PR (-2800 / +2000) I suggest that we try to decide whether it should get over the finish line or not, otherwise I worry it is going to become stale very quickly.

@agoose77 what is the information that you need in order to decide whether this spike is worth implementing entirely, or whether it's best to pursue other strategies for improving the static site workflow?

[agoose77]

@choldgraf the line diff is deceptive; most of the changed lines are in the lock file.

Given the rate of change in myst-theme, I think it will be fairly stable. At this point, I think the spike is close to done - the final day I've allocated to it will see whether static exports work (either with the remix server or vite). That will conclude the spike, and following feedback from the MyST team, we should have an idea of where to go next.

[stevejpurves]

@agoose77 wrt your last comment, did you look at and have conclusions around the out of the box static support with our current method? (i.e. without the transition to SSR-SPA)