A Little Rambling#

In my previous post, from late September, I ran into a problem while using localStorage in Nuxt. At first I thought my code design was wrong, but it turned out to be a hydration problem that needs to be avoided.

I wanted to write about it then. Real life was busy, my knowledge was limited, and SSR is deep water. I needed to do quite a lot of research before I could write even a short post, so it took me until now.

At first, I thought I only needed to explain hydration and list a few situations that trigger hydration issues. But hydration is shared by SSR (Server-Side Rendering) and SSG (Static Site Generation), so I also had to understand SSR and SSG. To understand them, I first had to understand rendering patterns in general. You can see why this got delayed.

Please forgive me for taking so long to finish such a short article.

That said, I realized that I have already worked with three projects involving SSR, including this blog. Astro uses island rendering, and I have modified parts of this blog as well. Maybe that gives me enough confidence to write about it.

Start with Rendering#

Rendering is the process that turns the usual front-end trio of HTML, CSS, and JavaScript into an actual page. I do not completely master the theory, so here is an explanation image from Gemini. The main thing to understand is that rendering takes time and has a cost. That is why different rendering patterns exist.

SSR means Server-Side Rendering. A rendering pattern describes how the browser turns front-end code into a web page. Here are two patterns that you have probably used even if you did not know their names.

Before Step One: Rendering on the Server#

From the user’s perspective this is not really the first step, because the server often prepares the HTML and JavaScript before the user arrives. The client only waits to receive them.

It is important that HTML and JavaScript are separate here. As I said above, JavaScript will be attached later through client hydration.

The server environment and the browser environment are different. Unlike CSR, SSR evaluates some application code on the server. That difference is the reason SSR code can easily produce certain errors, which I will show later.

Step One: Get the Static Files#

The client receives the HTML and JavaScript files prepared by the server and uses the HTML to fill the browser page. The user quickly sees a static page, which is one of SSR’s core advantages.

The JavaScript file has not done its job yet. It matters in the next step.

Step Two: Client Hydration#

This is SSR’s most distinctive and difficult-to-understand step. The JavaScript file that was not used in step one needs to be connected to the HTML that is already displaying a static page. Only after they are connected do we have a complete, interactive front-end page.

For example, imagine a login page. The server HTML can show a login button, but without JavaScript it is only an empty shell and cannot log anyone in. We need to attach @click="login()" and the login function itself. Connecting those pieces of JavaScript to the matching HTML elements is called hydration.

In short, hydration reconnects the HTML and JavaScript that should have been one page, but were separated during the server-rendering stage.

Step Three: Normal Client-Side Operation#

After hydration, the complete front end runs in the browser normally, just like a CSR application.

localStorage Cannot Be Used on the Server#

Assume a browser has a localStorage entry named API_KEY:

1
<script setup lang="ts">
2
const key = localStorage.getItem("API_KEY");
3
</script>

Will this work during SSR? No. You will get an error like this:

The problem happens in the pre-rendering step: the server does not have the localStorage API. It is a browser API for browser storage.

Moving the code into an imported helper does not solve it either:

1
import { getKey } from "~/use-key.ts";
2

3
const key = getKey();
4

5
export const getKey = () => {
6
  const key = localStorage.getItem("API_KEY");
7
  return key;
8
};

An import is still evaluated during server rendering, so it can still call browser-only APIs.

The basic safe shape is to access it only after mounting in the browser:

1
function getKey() {
2
  return localStorage.getItem("API_KEY");
3
}
4

5
onMounted(() => {
6
  getKey();
7
});

onMounted runs in step three, after the page has mounted in the client. That is why this version does not try to use localStorage on the server.

Some Requests Should Not Run on the Server#

It is common to write logic like “send a request when entering this page.” But some requests should not be sent during SSR.

For example, a request may require user-submitted data or authentication information such as a token. When server rendering runs, that user-specific browser state is not available, so sending the request is meaningless.

Nuxt provides <client-only> for this kind of situation:

1
<client-only>
2
  <!-- Content -->
3
</client-only>

You can wrap the part that sends the request in a component and put it inside <client-only>. It only renders during normal client-side operation, so the server does not make that request.

Errors During Client Hydration#

The example I wrote about in the previous post is a hydration problem. It is complicated enough that it deserved its own article.

Although that post is dated September, I rewrote its core solution after finishing this SSR Part 1, and revised the rest as well. You can read it here:

Fixing a Hydration Problem I Ran Into

References#

Video: 10 Rendering Patterns for Web Apps - the categories are broad, but it covers a lot.

Article: Understanding Hydration in React applications (SSR)

Bing search, ChatGPT, my project code, and my own brain.