The absurd complexity of server-side rendering

ssr.md

In the olden days, HTML was prepared by the server, and JavaScript was little more than a garnish, considered by some to have a soapy taste.

After a fashion, it was decided that sometimes our HTML is best rendered by JavaScript, running in a user's browser. While some would decry this new-found intimacy, the age of interactivity had begun.

But all was not right in the world. Somewhere along the way, we had slipped. Our pages went uncrawled by Bing, time to first meaningful paint grew faster than npm, and it became clear: something must be done.

And so it was decided that the applications first forged for the browser would also run on the server. We would render our HTML using the same logic on the server and the browser, and reap the advantages of both worlds. In a confusing series of events a name for this approach was agreed upon: Server-side rendering. What could go wrong?

In dark rooms, in hushed tones, we speak of colours. We joke of nulls, commiserate about queues, but of colours we only whisper.

That is because colours can hurt you. We shield our juniors from this knowledge, not because it's the wise thing to do, because once you confront the abyss there's no turning back.

The common colours are no secret. Is a function synchronous or asynchronous? Does it mutate the arguments provided, or meekly return a value? Do I need to worry about it throwing an exception?

In a certain light, colours are merely a way to categorise certain types of functions. Functions of a like colour can be used together without much consideration.

It doesn't take much examination to see that colours beget complexity. Much of the art of application-level architecture is appropriately reducing and grouping colours to oppose this complexity.

In the olden days, we had few colours to worry about. The task of managing incoming connections was abstracted to a simple mapping of request to response.

All functions blocked execution for a while. Some would talk to databases or queues, and we were either content to wait, or to fire and forget while we returned the response.

It's different in the browser. Our code competes with the user's ability to interact, and therefore we must be careful. We embrace asynchronous code, and with it all the complexity that comes from another colour.

Server-side rendering (SSR) poses yet another problem on top of this one. Some functions were not designed to be used in both Node and the browser, and so we find another colour lurking.

In order to support applications that make use of both server coloured functions and client coloured functions, bundlers were built, as clever as they are obtuse.

Say you want to read a file as part of a request. This is only allowed in certain functions, designated by the framework to be server-coloured.

You cannot use a server-coloured function at the top level, since that implies it should be included in your browser, and you cannot use a client-coloured function with the framework's server-coloured functions.

Next.js describes this approach as "smart bundling". This may be smart, but it is not wise.

It's hard enough to ensure that you're only using the correctly coloured function in the right place, until you consider that one of the main advantages of this sort of framework is sharing code across the server and the client.

It's entirely up to you to ensure that you correctly manage your function colours. If you accidentally use the wrong sort of function in your shared code, your application will not work.

If you're lucky, the bundler will catch this and throw a seemingly unrelated error. More likely, you'll experience a cryptic runtime error, followed by days of agony if you don't understand this problem. There is very little available in the way of static analysis to make this easier.

To me, this seems like a very bad idea. What's worse, this important colour is generally treated as a footnote by the creators of these frameworks. Most developers only realise how bad this problem is when it's too late.

I don't think that SSR apps are fundamentally a bad idea. That said, the way we're going about it right now is terrifyingly complex and error-prone.

If you're considering using one of these frameworks, I would recommend you carefully consider if the complexity is worth it, especially for less-experienced members of your team.

For those who do pursue SSR, I advise you to work towards better static analysis to help manage these problems. Rust has built a career by explicitly recognising that lifetimes exist and that we need better tools to work with them. A similar opportunity exists here for SSR apps.

Heres the bottom line, if you don't like what you are doing, you are not likely to do a good job at it.
In short these are subjective problems to the individual. My truth is not your truth, ect.

People need to stop trying to put a fucking label on everyone and just go forge their own paths.
I hate SPAs, but I know so many do great work with them, does not mean SPAs are bad just because I don't like them.
It just means I don't like them.
So I don't do them, problem solved.

Hey @oshox – one of the designers of Next.js here. We've also identified the issue you've run into, and we're introducing 🅰️ a filesystem convention (.server.ts) for more cleanly separating client and server component trees, as well as focusing the rendering layer on a 🅱️ Web standards runtime. This makes bundling and DX a breeze, in my opinion.

This work is ongoing and looking really promising already. SSR is getting easier, faster, cheaper, and edgier than ever 😄

I think Remix uses this filesystem separation convention .server.ts and .client.ts, which helps devs explicitly separate concerns.

@rauchg thanks for engaging with this post and sharing upcoming improvements to the SSR story. Out of curiosity, is anything planned to improve UX when a user accidentally calls server/client specific code from a shared function?

Just as an aside for people reading this, please keep your comments civil and considerate. Contempt culture is not welcome here.

I believe collectively there are many developers that are tired of the promise of a framework solving all their problems. IMO the problem always comes down to complexity. If a system becomes over complex, there are more problems that need to be solved. We need to work on not solving all the problems, but rather, taking a step back and trying to simplify. The JS community has become a confusing mess of frameworks, "standards", and build tools.

.. Don't believe me. Ask 10 different developers how to write a React app. You WILL get 10 different answers. It's ok to get answers that vary slightly ( of course they will ). However, it will more likely vary A LOT.

Why is this sad and annoying... because this is just 10 different devs using React. Not to mention the 700 other ways people can create "modern" web apps. There is little consistency.

@joepuzzo The complexity goes either into the framework stack or the boilerplate. People maintaining existing sites will obviously have a different perspective, but tapping into the years' of experience that framework maintainers possess is a great experience for new developers.

I fear we continue to re-invent the wheel. Constantly rebuilding our foundations, preventing us from building upwards. Making it hard for people to share.

Much like the layers of the OSI model, the ability to build new amazing higher level things is achieved because a layer stabilizes. This stabilization allows us to build upwards. The web layer as it stands is far from stable.

I wish the years of experience worked towards a more unified direction. It feels to me like people are running in 7 different directions.

ArticleA/PersonA: "Module federation is the future of the web"
ArticleB/PersonB: "Remix is the future"
ArticleC/PersonC: "Next Js is the future"
.... on and on

Agree with @joepuzzo
After years in this industry, I’ve had to relearn how to render and style a button in more frameworks and “best practices” than I can count.

Next.js is awesome. I’ve had a pleasant experience with it and know many others, from big and small companies, who have as well.

But, at the same time, it is frustrating that with the combined genius of the JS community, we’re still debating what color the wings should be instead of flying to Mars.

@charlesponti Yes! I often Joke with other developers about how many different ways you can put a button on a screen and hook it up. Every time the button looks the same, ultimately does the same thing, yet it's completely different.

Im not saying it's not good to have different options, many are quick to make that argument to me. However, i'm simply asking what is our gain? Is the new way really so much better than the old way... does it REALLY allow me to move quicker and build higher.

I would be interested to see the web community stop throwing around different types of mud as the foundation. "My mud is better than your mud". Would be cool to have a stable foundation that we can build on.

Occasional whispers of function colors is the only thing keeping me going. Thanks.

For an alternative perspective on this, I'm the developer of Perseus, a Rust framework that supports SSG, SSR, incremental rendering, etc. From my experience, a lot of the problems of mixing server-side and client-side code come from ambiguities in dependency management and misunderstandings about how state is passed through an application.

Compiled languages like Rust, while much slower in compiling apps, are often faster at runtime (Perseus scores better than Svelte in some Lighthouse metrics, for example, though Wasm still has a way to go on some DOM optimizations), and they're usually much better at delineating dependencies. For example, I can easily declare a 'crate' (Rust dependency) that's only used on the server, and separate that from one used only on the client.

The big misunderstanding I've found from a lot of my framework's users is with regards to fetching data, and the ambiguities of doing one thing on the server-side and a quite different thing on the client-side. I think that can be partially solved by putting server-side code in a different file, but the important thing is to have clear state flows through apps. You generate state in one place, and then it's processed by the framework, and then you can use it in another place.

Fundamentally, SSR should, in my opinion, be about state generation. It's easy enough to optimize apps to prerender some HTML on the server these days, the tricky part comes when you're figuring out what to load and when (you need to load user-specific information in the browser, product-specific information on the server at runtime with caching, layouts at build-time, etc.). To make sense of that for users, I think framework developers (myself 100% included) have to make what the 'black box' framework is doing more transparent. When people think the data they fetch on the server-side is shared magically with the browser, misunderstandings pop out far too easily. If we can make it clear that the data are serialized, stored as JSON, passed over the network in some way, deserialized, processed, interpolated, made reactive, etc., and if we can communicate that in a beginner-friendly way (still working on that one...), then I think we can start to fix this issue.

The reason a lot of frameworks have these kinds of problems as a footnote is I think because the developers don't see them as a problem. When you've built a system for moving state around, and you understand it, things are clear to you. Then, suddenly someone starts asking about why they can't use a server-side function in a different place, and it's obvious to you because you know how state flows through the app, but not to them, because the documentation treats the framework's internals as something you shouldn't have to worry about. I think that's the information we need to get across to users if we want to solve this problem long-term without making significant infrastructural changes to the existing framework landscape (and, if we were to make such changes, I think, as the comments on this post prove, the best approach is far from universally agreed).

As a side note going to @joepuzzo's point, I think making the internals of frameworks more transparent in documentation would go a long way to fostering a more productive environment in framework development. When we can all learn from each other, and figure out why one framework is faster than another, regardless of our skill level in a particular language, we can hopefully bring one framework's advantages to another framework. The open-source community should be about cooperation, not competition.

Cool looking framework @arctic-hen7, I'll definitely look more closely at that later. I agree with a lot of that, and I'd certainly appreciate framework authors working to make their model easily understandable.

What I'd personally really like though is the ability to have this kind of thing guaranteed, and in a language like Scala or Haskell that'd be pretty standard. Have you considered representing runtime requirements on the typesystem, allowing users to effectively tag functions as only supporting one, the other, or both with different implementations? Curious to hear your thoughts as someone living and breathing this problem space.

Thanks @MiriChan! In Rust, you can very easily gate a function for a compile target with #[cfg(target_arch = "wasm32")], for example. That's used quite extensively in Perseus' internals, but I think it would be good to bring it more to the fore in user-written code -- making those runtime requirements coded into the type system more regularly is something I really want to work on over the coming releases.

As an example, I just changed some code in Perseus' internals so that a particular part of the app setup system that registers the equivalent to index.html only runs a necessary regex replacement on the server-side, which means I don't have to bring the regex crate into the Wasm bundle. That's very clearly notated in the code, and the errors produced from misuse then make reasonable sense.

Out of curiosity, is anything planned to improve UX when a user accidentally calls server/client specific code from a shared function?

@Widdershin Yep (Next.js team here)! First of all, many of the server/client specific code will fail if calling from a wrong environment, these can be found early during development. And generally, a shared component should try to behave the same in server/client as much as possible and not introduce such a branching.

But still, you can 1) use the typeof window === 'undefined' condition to distinguish the actual code runtime and add browser specific code. This covers most of the cases. And 2), we’re thinking about adding a global constant or environment variable like globalThis.NEXT_SERVER_COMPONENT for any shared component to tell if it’s being treated as a server or client component.

As a side note going to @joepuzzo's point, I think making the internals of frameworks more transparent in documentation would go a long way to fostering a more productive environment in framework development. When we can all learn from each other, and figure out why one framework is faster than another, regardless of our skill level in a particular language, we can hopefully bring one framework's advantages to another framework. The open-source community should be about cooperation, not competition.

This! I know for some reason comparison is discouraged but questioning and comparing solutions, techniques is engineering/science 101. I am very curious as to why NextJS went the AngularJS (OG 1.x) route of 'magic'. What were the motivating reasons to go with a brand new set of APIs? Now I have to learn NextJS things like getServerSideProps etc. Remix seems like React of SSR and is promising in the sense that it rests on web fundamentals for the most part with 'add-ons' but that said would be curious to see the limitations of nested layouts. It also makes the dev actually wire up RenderToString/Hydrate or RenderToPipeableStream/HydrateRoot (which NextJS does under-the-hood) so the amount of magic is lower but some magic is still present.

If both frameworks can write out a technical article (which isn't dumbed down magic & cool focused) on what their code does under-the-hood, it would be of massive help for developers who have been programming in the web for around a decade if not more. There is a network chasm diagram with Remix explaining high level, but more technical articles would be awesome. That would be a welcome change in both SSR framework blogs, which solely seem to target only new devs, who have little or no exposure to old school just because of when they entered the field. As a community, our focus shouldn't be on wrapping the eyes of devs with magic but to show them how the magic works and what it does :)

Just today i joked with my colleagues about the history of the web. Back then, when we used PHP for SSR, the path to SPA over the JAM Stack over ISG (Incremental Page Generation) to full SSR again (with hydration or without ) XD. Everything comes back. Maybe the ideas brought up by PHP werent that bad.

One thing is very sure for me. This giant mess with bundlers, build tools, different environments and other stuff needed, introduces a lot of complexity which isnt going anywhere. We have to live with it and thats completely ok for ME because I really like to dig deep.

For newbies tho this is extremely problematic because nobody of them learns it like this: html --> css --> jQuery --> native js --> sprinkle some vue in it --> and then using a full blown SPA Framework.

Its more like that: Oh cool i want to build a website --> Next, Nuxt, Svelte, Vue, Remix, Gatsby,...

WE have the responsiblity to teach the "correct" way... because only then they can decide which technology is best used for.

That brings me to my last point. All of those technologies are great when used for the right purpose but this decision is only possible if you understand how it works and know the drawbacks.

First of all, many of the server/client specific code will fail if calling from a wrong environment

you can 1) use the typeof window === 'undefined' condition to distinguish ... we’re thinking about adding a global constant or environment variable like globalThis.NEXT_SERVER_COMPONENT

@shuding if I'm understanding @Widdershin's original post correctly (although I do think that the point is a bit exaggerated - the benefits far outweigh the drawbacks), I think they are aware of the above, and mean that this is still difficult to deal with, when it fails.

In teaching Next.js to beginner students at @upleveled (and seeing the problems isomorphism / universal JS causes in the wild), I have also experienced this - eg. a runtime call to something that works on the server-side but then fails on the client (or vice versa). Even worse if it causes an intermittent error that only shows up on full page refresh.

Maybe it would be possible to have some kind of static analysis in @next/eslint-plugin-next to try to warn developers about incorrect Node.js vs browser API usage as early as possible - in the editor / linting CI step already. Seems like a larger undertaking though, to identify all of the browser / Node.js APIs and also the "safe" areas of the code - eg. in shared components with getServerSideProps, getStaticProps or getInitialProps...

It's not fun trying to work in muddied waters.

@Widdershin it’s hard to pick a “you’re right/wrong/somewhere in the middle” stance when your post is not including the code (or a more in depth description) that caused your bad experience with ssr.

In my experience ssr in nextjs doesn’t get in the way of the stuff I do. Do I need some code to run only in the client? I should place it inside a useEffect callback without deps. That’s it.

Could my milage have varied? Maybe.

I would argue react hooks has brought me way way more unexpected behavior/performance usage.

Ssr though? Pretty transparent to me, with minor issues here and there. The benefit? The page loads pretty fast.

its just serving html files mate its not that deep

@shuding another example of things that could be focused on a bit more are edge cases for imports and bundling for server-side rendering.

Eg. this issue that I just found with using a file with shared server + client exports in Next.js - this causes bundling of the (unused) server code, leading to the dreaded Can't resolve 'fs'. This seems like a bug to me:

vercel/next.js#36514

Going even a bit further with this, there could be more work done to guide developers into the "pit of success" - more heuristics and development-time messaging to teach them how to do server-side rendering properly, by only accessing client or server variables.

All those javascript frameworks first create problem then tries to solve claiming they are speedy... OMG
Side note for maintainer of next.js - stop using latest-very-best javascript syntax like ,? .? or the like. Not everyone can upgrade to 200 version of browsers.