DEV Community: Denis Gonchar

Next.js: How and Components Streaming works?

Denis Gonchar — Tue, 12 Sep 2023 20:55:00 +0000

There is a distinct difference between ‘suspense’ and ‘surprise’, and yet many pictures continually confuse the two. I’ll explain what I mean. We are now having a very innocent little chat. Let’s suppose that there is a bomb underneath this table between us. Nothing happens, and then all of a sudden, ‘Boom!’ There is an explosion. The public is surprised, but prior to this surprise, it has seen an absolutely ordinary scene, of no special consequence.

Alfred Hitchcock

In this article, we'll dive into the specifics of the <Suspense /> tag as it relates to Next.js and Server Side Rendering (SSR) feature. We'll delve deeper to see what happens at the HTTP protocol level when you wrap your components with the tag. Let's begin.

Streaming, what is it?

Before we dive into "Components Streaming" it's essential to understand what HTTP streaming is in and of itself. When your User Agent (for example, a browser or a curl command) sends an HTTP request to a server, the server replies with something like:

HTTP/1.1 200 OK␍␊
Date: Mon, 27 Jul 2009 12:28:53 GMT␍␊
Content-Length: 12␍␊
Content-Type: text/plain␍␊
␍␊
Hello World!

I've added the ␍␊ to HTTP response texts because it carries a special meaning in HTTP.

The first line, HTTP/1.1 200 OK, tells us that everything is fine and the server has responded with a 200 OK code. Following this, we have three lines that are known as headers. In our example, these three headers are Date, Content-Length, and Content-Type. We can think of them as key-value pairs, where the keys and values are delimited by a : sign.

Following the headers, there's an empty line, serving as a delimiter between the header and the body sections. After this line, we encounter the content itself. Given the prior information from the headers, our browser understands two things:

It needs to download 12 bytes of content (the string Hello World! comprises just 12 characters).
Once downloaded, it can display this content or provide it to the callback of a fetch request.

In other words, we can deduce that the end of the response body will occur once we've read 12 bytes following a new line.

Now, what happens if we omit the Content-Length header from our server response? When the Content-Length header is absent, many HTTP servers will implicitly add a Transfer-Encoding: chunked header. This type of response can be interpreted as, "Hi, I'm the server, and I'm not sure how much content there will be, so I'll send the data in chunks." So a response will look like:

HTTP/1.1 200 OK␍␊
Date: Mon, 27 Jul 2009 12:28:53 GMT␍␊
Transfer-Encoding: chunked␍␊
Content-Type: text/plain␍␊
␍␊
5␍␊
Hello␍␊

At this point, we haven't received the entire message, only the first 5 bytes. Notice how the format of the body differs: first, the size of the chunk is sent, followed by the content of the chunk itself. At the end of each chunk, the server adds a ␍␊ sequence.

Now, let's consider receiving the second chunk. How might that appear?

HTTP/1.1 200 OK␍␊
Date: Mon, 27 Jul 2009 12:28:53 GMT␍␊
Transfer-Encoding: chunked␍␊
Content-Type: text/plain␍␊
␍␊
5␍␊
Hello␍␊
7␍␊
 World!␍␊

We've received an additional 7 bytes of the response. But what transpired between Hello␍␊ and 7␍␊? How was the response processed in that interval? Imagine that before sending the 7, the server took 10 seconds pondering the next word. If you were to inspect the Network tab of your browser's Developer Tools during this pause, you'd see the response from the server had started and remained "in progress" throughout these 10 seconds. This is because the server hadn't indicated the end of the response.

So, how does the browser determine when the response should be treated as "completed"? There's a convention for that. The server must send a 0␍␊␍␊ sequence. In layman's terms, it's saying, "I'm sending you a chunk that has zero length, signifying there's nothing more to come." In the Network tab, this sequence will mark the moment the request has concluded.

HTTP/1.1 200 OK␍␊
Date: Mon, 27 Jul 2009 12:28:53 GMT␍␊
Transfer-Encoding: chunked␍␊
Content-Type: text/plain␍␊
␍␊
5␍␊
Hello␍␊
7␍␊
 World!␍␊
0␍␊
␍␊

The Nuances of HTTP Transmission

In the realm of HTTP headers, understanding the distinction between Content-Length: <number> and Transfer-Encoding: chunked is crucial. At a first glance, Content-Length: <number> might suggest that data isn't streamed, but this isn't entirely accurate. While it's true that this header indicates the total length of the data to be received, it doesn't imply that data is transmitted as a single massive chunk. Underneath the HTTP layer, protocols like TCP/IP dictate the actual transmission mechanics, which inherently involves breaking data down into smaller packets. So, while the Content-Length header gives a system the signal that once it accumulates the specified amount of data, it's ready for rendering, the actual data transfer is executed incrementally at a lower level. Some contemporary browsers, capitalizing on this inherent packetization, initiate the rendering process even before the entire data is received. This is particularly beneficial for specific data formats that lend themselves to progressive rendering. On the other hand, the Transfer-Encoding: chunked header offers more explicit control over data streaming at the HTTP level, marking each chunk of data as it's sent. This provides even more flexibility, especially for dynamically generated content or when the full content length is unknown at the outset.

`<Suspense />`

Alright, now we've grasped one foundational concept that's pivotal for Component Streaming in Next.js. Before delving into <Suspense />, let's first articulate the problem it addresses. Sometimes, seeing is more instructive than a lengthy explanation. So, let's craft a helper function for illustration:

export function wait<T>(ms: number, data: T) {
  return new Promise<T>((resolve) => {
    setTimeout(() => resolve(data), ms);
  });
}

This function will assist us in simulating exceedingly prolonged, fake requests.

To start, initialize a Next.js app using npx create-next-app@latest. Clear out any unnecessary elements, and paste the following code into app/page.tsx:

import { wait } from "@/helpers/wait";

const MyComponent = async () => {
  const data = await wait(10000, { name: "Denis" });
  return <p>{data.name}</p>;
};

export const dynamic = "force-dynamic";

export default async function Home() {
  return (
    <>
      <p>Some text</p>
      <MyComponent />
    </>
  );
}

This structure provides a simple page layout: a text block containing “Some text” and a component that waits for 10 seconds before outputting the data.

Now, execute npm run build && npm run start followed by a curl localhost:3000 (or try to open it in a browser) command. What do we observe?

We experience a delay of 10 seconds before receiving the entire page content, including both “Some text” and “Denis”. For users, this means they won't be able to view the “Some text” content while <MyComponent /> is fetching its data. This is far from ideal; the browser tab's spinner would keep spinning for a solid 10 seconds before displaying any content to the user.

However, by wrapping our component with the <Suspense/> tag and trying again, we observe an instantaneous response. Let's delve into this method. We encase our component in <Suspense> and also assign a fallback prop with the value "We are loading...".

export default async function Home() {
  return (
    <>
      <p>Some text</p>
      <Suspense fallback={"We are loading..."}>
        <MyComponent />
      </Suspense>
    </>
  );
}

Now let us open it in a browser.

Now, we observe that the string provided as the fallback prop for <Suspense /> temporarily stands in for the <MyComponent />. After the 10-second wait, we're then presented with the actual content. Let's scrutinize the HTML response we've received.

<!DOCTYPE html>
<html lang="en">
<head>
    <!-- Omitted -->
</head>
<body class="__className_20951f">
    <p>Some text</p><!--$?-->
    <template id="B:0"></template>
    Waiting for MyComponent...<!--/$-->
    <script src="/_next/static/chunks/webpack-f0069ae2f14f3de1.js" async=""></script>
    <script>(self.__next_f = self.__next_f || []).push([0])</script>
    <script>self.__next_f.push(/* Omitted */)</script>
    <script>self.__next_f.push(/* Omitted */)</script>
    <script>self.__next_f.push(/* Omitted */)</script>
    <script>self.__next_f.push(/* We haven't received a chunk that closes this tag...

While we haven't yet received the complete page, we can already view its content in the browser. But why is that possible? This behavior is due to the error tolerance of modern browsers. Consider a scenario where you visit a website, but because a developer forgot to close a tag, the site doesn't display correctly. Although browser developers could enforce strict error-free HTML, such a decision would degrade the user experience. As users, we expect web pages to load and display their content, regardless of minor errors in the underlying code. To ensure this, browsers implement numerous mechanisms under the hood to compensate for such issues. For instance, if there's an opened <body> tag that hasn't been closed, the browser will automatically "close" it. This is done in an effort to deliver the best possible viewing experience, even when faced with imperfect HTML.

And it's evident that Next capitalizes on this inherent browser behavior when implementing Component Streaming. By pushing chunks of content as they become available and leveraging browsers' ability to interpret and render partial or even slightly malformed content, Next.js ensures faster perceived load times and enhances user experience.

The strength of this approach lies in its alignment with the realities of web browsing. Users generally prefer immediate feedback, even if it's incremental, over waiting for an entire page to load. By sending parts of a page as soon as they're ready, Next.js optimally meets this preference.

Now, observe this segment:

<!--$?-->
  <template id="B:0"></template>
  Waiting for MyComponent...
<!--/$-->

We can spot our placeholder text adjacent to an empty <template> tag bearing the B:0 id. Further, we can discern that the response from localhost:3000 is still underway. The trailing script tag remains unclosed. Next.js uses a placeholder template to make room for forthcoming HTML that will be populated with the next chunk.

After the next chunk has arrived, we now have the following markup (I’ve added some newlines to make it more readable)...

Don't attempt to unminify the code of the $RC function in your head. This is the completeBoundary function, and you can find a commented version here.

<p>Some text</p>

<!--$?-->
<template id="B:0"></template>
Waiting for MyComponent...
<!--/$-->

<!-- <script> tags omitted -->

<div hidden id="S:0">
  <p>Denis</p>
</div>

<script>
  $RC = function (b, c, e) {
    c = document.getElementById(c);
    c.parentNode.removeChild(c);
    var a = document.getElementById(b);
    if (a) {
      b = a.previousSibling;
      if (e)
        b.data = "$!",
          a.setAttribute("data-dgst", e);
      else {
        e = b.parentNode;
        a = b.nextSibling;
        var f = 0;
        do {
          if (a && 8 === a.nodeType) {
            var d = a.data;
            if ("/$" === d)
              if (0 === f)
                break;
              else
                f--;
            else
              "$" !== d && "$?" !== d && "$!" !== d || f++
          }
          d = a.nextSibling;
          e.removeChild(a);
          a = d
        } while (a);
        for (; c.firstChild;)
          e.insertBefore(c.firstChild, a);
        b.data = "$"
      }
      b._reactRetry && b._reactRetry()
    }
  }
  ;
  $RC("B:0", "S:0")
</script>

We receive a hidden <div> with the id="S:0". This contains the markup for <MyComponent />. Alongside this, we are presented with an intriguing script that defines a global variable, $RC. This variable references a function that performs some operations with getElementById and insertBefore.

The concluding statement in the script, $RC("B:0", "S:0"), invokes the aforementioned function and supplies "B:0" and "S:0" as arguments. As we've deduced, B:0 corresponds to the ID of the template that previously held our fallback. Concurrently, S:0 matches the ID of the newly acquired <div>. To distill this information, the $RC function essentially instructs: "Retrieve the markup from the S:0 div and position it where the B:0 template resides."

Let's refine that for clarity:

Initiating the Chunked Transfer: Next.js begins by sending the Transfer-Encoding: chunked header, signaling the browser that the response length is undetermined at this stage.
Executing Home Page: As the Home page executes, it encounters no await operations. This means no data fetching is blocking the response from being sent immediately.
Handling the Suspense: Upon reaching the tag, it uses the fallback value for immediate rendering, while also inserting a placeholder <template /> tag. This will be used later to insert the actual HTML once it's ready.
Initial Response to the Browser: What's been rendered so far is sent to the browser. Yet, the "0␍␊␍␊" sequence hasn't been sent, indicating the browser should expect more data to come.
Component Data Request: The server communicates with MyComponent, requesting its data and essentially saying, "We need your content, let us know when you're ready."
Component Rendering: After MyComponent fetches its data, it renders and produces the corresponding HTML.
Sending the Component's HTML: This HTML is then sent to the browser as a new chunk.
JavaScript Attachment: The browser's JavaScript then appends this new chunk of HTML to the previously placed tag from step #3.
Termination Sequence: Finally, the server sends the termination sequence, signaling the end of the response.

Diving into Multiple `<Suspense />`

Handling a singular <Suspense /> tag is straightforward, but what if a page has multiple of them? How does Next.js cope with this situation? Interestingly, the core approach doesn't deviate much. Here's what changes when managing multiple <Suspense /> tags:

Fallbacks at the Forefront: Each <Suspense /> tag comes equipped with its own fallback. During the rendering phase, all these fallback values are leveraged simultaneously, ensuring that every suspended component offers a provisional visual cue to the user. This is an extension of the third point from our previous list.

Unified Request for Content: Just as with a single <Suspense />, Next.js sends out a unified call to all components wrapped within the <Suspense /> tags. It's essentially broadcasting, "Provide your content as soon as you're ready."

Waiting for All Components: The termination sequence is of utmost importance, signaling the end of a response. However, in cases with multiple <Suspense /> tags, the termination sequence is held back until every single component has sent its content. This ensures that the browser knows to expect, and subsequently render, the content from all components, providing a holistic page-view to the end user.

The advent of features like <Suspense /> in Next.js underscores the framework's dedication to enhancing user experience. By tapping into the innate behavior of browsers and optimizing content delivery, Next.js ensures users encounter minimal wait times and see content as swiftly as possible. This deep dive into the inner workings of component streaming and chunked transfer encoding reveals the intricate dance of protocols, rendering, and real-time adjustments that takes place behind the scenes. As web developers, understanding these nuances not only makes us better at our craft but also equips us to deliver seamless and responsive digital experiences for our users. Embrace the future of web development with Next.js, where efficiency meets elegance.

Unlocking the Puzzle: Investigating Multiple Event Listeners in Vue.js

Denis Gonchar — Sun, 27 Aug 2023 15:48:40 +0000

In this article, we will tackle a question: Does Vue.js support multiple event listeners? Our journey will take us deep into the mechanics of Vue.js, unraveling some intriguing undocumented behaviors along the way.

Let's begin with a closer look at the official documentation on "Event Handling" in Vue.js. The primary method of attaching an event listener is through the v-on:click="handler" syntax, which can also be simplified as @click="handler". In this syntax, the handler refers to a reference to a function. Additionally, in the "Inline Handlers" section, it's highlighted that you can employ arbitrary JavaScript code directly within the attribute. For instance, you can use @click="count++" to increment a variable. An important note is provided in the "Method vs. Inline Detection" section, which indicates that

The template compiler detects method handlers by checking whether the v-on value string is a valid JavaScript identifier or a property access path.

So, does Vue support multiple listeners? The answer seems to lean towards no, but it's not entirely clear-cut.

Let recap it with the code:

<script setup>
import { ref } from 'vue';

const count = ref(0);
function inc() { count.value += 1; }
</script>

<template>
  <h3>{{ count }}</h3>
  <button @click="count++">Incremenet by count++</button>
  <button @click="inc">Incremenet by ref</button>
  <button @click="inc()">Incremenet by call</button>
  <button @click="() => inc()">Incremenet by lambda</button>
</template>

Now, let's take a plunge into the JS tab within the Vue SFC Playground to closely examine how the Vue.js compiler has compiled these listeners.

We will encounter the following code snippet (I've omitted the _cache[0] || (_cache[0] = $event => (count.value++)) portions for the sake of readability):

_createElementVNode("h3", null, _toDisplayString(count.value), 1 /* TEXT */);

// @click="count++" will be compiled to...
_createElementVNode(
  "button",
  {
    onClick: ($event) => count.value++,
  },
  "Incremenet by count++",
);

// @click="inc" will be compiled to...
_createElementVNode("button", { onClick: inc }, "Incremenet by ref");

// @click="inc()" will be compiled to...
_createElementVNode(
  "button",
  {
    onClick: ($event) => inc(),
  },
  "Incremenet by call",
);

// @click="() => inc()" will be compiled to...
_createElementVNode(
  "button",
  {
    onClick: () => inc(),
  },
  "Incremenet by lambda",
);

The behavior is indeed intriguing. When a reference to inc is passed, the compiler simplifies it to { onClick: inc }. However, for count++, inc() and () => inc(), the compiler follows a distinct route. It encapsulates the code enclosed within the template's " into a lambda function and then proceeds to execute it exactly as it's written. This observation offers valuable insight: if the compiler wraps code within a lambda, we can leverage native JavaScript capabilities to call multiple functions within a single expression using fn1(); fn2() or fn1(), fn2(). Let's try it.

We will introduce another function, showAlert(), which will invoke the native alert() function and pass count.value into it. You can access the updated Playground here. Here is the code:

// @click="count++, showAlert()" will be compiled to...
_createElementVNode(
  "button",
  {
    onClick: ($event) => (count.value++, showAlert()),
  },
  "Increment by count++",
);

// How to pass multiple refs?
_createElementVNode("button", { onClick: inc }, "Increment by ref");

// @click="inc(); showAlert()" will be compiled to...
_createElementVNode(
  "button",
  {
    onClick: ($event) => {
      inc();
      showAlert();
    },
  },
  "Increment by call",
);

// @click="() => (inc(), showAlert())" will be compiled to...
_createElementVNode(
  "button",
  {
    onClick: () => (inc(), showAlert()),
  },
  "Increment by lambda",
);

For @click="count++, showAlert()", @click="inc(); showAlert()", and @click="() => (inc(), showAlert())", everything works fine, allowing us to call multiple functions for a single event.

The issue arises when dealing with the ref case. How can we pass multiple refs into the @click="..." handler? The official documentation is notably silent on the topic of passing multiple references. It appears that this feature might not be supported, leaving us unable to achieve this behavior directly.

To explore this further, let's experiment with the two initial approaches that come to mind: fn1, fn2 and [fn1, f2], and observe how they are compiled by Vue.js.

// @click="inc, showAlert" will be complied to...
_createElementVNode("button", {
  onClick: $event => (inc, showAlert)
}, "Multiple refs 1");

// @click="[inc, showAlert]" will be complied to...
_createElementVNode("button", {
  onClick: $event => ([inc, showAlert])
}, "Multiple refs 2")

Unfortunately, both attempts do not yield success. Vue.js compiles these expressions in a manner that involves encapsulating the code enclosed within the template's ". This approach is consistent with the behavior we previously uncovered.

Let's take a step back and examine the scenario where we simply pass a function identifier without any accompanying () braces in the event handler.

// @click="inc" will be compiled to...
_createElementVNode(
  "button",
  { onClick: inc },
  "Incremenet by ref",
);

Vue simply maps inc to onClick. Now, let's recap the rule we extracted from the documentation.

The template compiler detects method handlers by checking whether the v-on value string is a valid JavaScript identifier or a property access path.

Incorporating the insights gained from the above, we can rephrase this rule as follows:

If the string within the template's v-on or @event, is recognized as a valid JavaScript identifier, Vue.js compiler will directly map it to { onEvent: <Valid JS Identifier> }.

Or like this:

Using only the name of a variable or a function will result in direct mapping.

Our revised definition omits any reference to a "method" handler; it purely states that when a valid identifier is used, it is directly passed as is. This implies that you can even pass a numeric value like 1337 to an onClick handler, provided you first create an identifier (in other words, a variable) that's bound to the value.

Passing a number as a handler clearly won't yield the desired results. However, as we recall, our aim is to pass multiple handlers as an array of refs. Given our newly established understanding, this is achievable. However, the prerequisite is to create a "valid JS Identifier (variable)" to store the reference to the array. Let's put this into action and see the results.

Take a look here. An interesting observation unfolds.

Firstly, using a "valid JS Identifier (variable)" named multiple, we successfully pass an array to onClick, and it gets mapped accordingly.

However, TypeScript expresses its discontent. It raises an error stating:

Type '(() => void)[]' is not assignable to type '(payload: MouseEvent) => void'.

Type '(() => void)[]' provides no match for the signature '(payload: MouseEvent): void'.ts(2322)

In essence, the types within Vue.js prevent us from passing an array of functions as a click listener.

Let's set this aside for now and simply click on the button to observe whether both listeners will be invoked. And yes, they are. We witness the counter value incrementing, followed by the appearance of the alert. But hold on, there's a puzzle to solve. Why is this functioning? What's going on behind the scenes?

To comprehend this, we must delve deeper and grasp the mechanics underlying the translation of Vue's VNode, created by the _createElementVNode function, into a native DOM element. The key lies in exploring the source code of Vue.js itself!

When we call the createApp() function in our main app.js or index.js, it triggers a chain of events that leads to the execution of the createRenderer() function (look for createApp function here). This sequence results in the formation of an app instance, complete with a mount() method. This method establishes an association with the renderer (see ensureRenderer() here). This renderer's primary task is to convert our VNodes into the native DOM elements we interact with.

Here's an overview of the key steps:

We compile our template, resulting in a series of _createElementVNode() calls.
These calls build our Virtual DOM, generating VNodes.
The renderer then traverses these nodes, converting them into native DOM elements.

As the renderer transforms VNodes into native DOM elements, it performs additional tasks using the props object of a VNode through the patchProp method.

Additionally, note that the createRenderer(rendererOptions) function is invoked with extended rendererOptions, encompassing a "patched" patchProp method. Let's delve into this for further understanding.

export const patchProp: DOMRendererOptions['patchProp'] = (
  // Omitted params...
) => {
  if (key === 'class') {
    patchClass(el, nextValue, isSVG)
  } else if (key === 'style') {
    patchStyle(el, prevValue, nextValue)
    // Keep in mind that we provide an object containing on<EventName> keys.
    // `isOn(key)` will return true for these keys.
  } else if (isOn(key)) {
    if (!isModelListener(key)) {
      // If the listener isn't intended for `v-model`, we utilize the `patchEvent` mechanism.
      patchEvent(el, key, prevValue, nextValue, parentComponent)
    }
  } // ...

We can interpret the code as follows: "If a prop is class, apply special handling based on class values. If a prop is style, implement special handling based on style values. And if a prop begins with on, perform specific actions using patchEvent."

Let's direct our attention to the patchEvent method. We've reached the bottom where Vue establishes native event bindings through the browser's addEventListener() method. However, prior to this step, there are additional operations in play. The high-level call chain is as follows:

patchEvent() is invoked.
It proceeds to call createInvoker() in order to generate an invoker function.
Inside the invoker, we invoke callWithAsyncErrorHandling, passing a wrapped version (altered by patchStopImmediatePropagation) of the value provided in the @click="..." event handler.

Now, let's examine patchStopImmediatePropagation to uncover the answer to the question: "Why does passing multiple refs to a function work?"

function patchStopImmediatePropagation(
  e: Event,
  value: EventValue
): EventValue {

  // If the value is an array, there's even more to explore! 
  // We can call $event.stopImmediatePropagation()
  // and other functions within the array won't be invoked.
  if (isArray(value)) {
    const originalStop = e.stopImmediatePropagation
    e.stopImmediatePropagation = () => {
      originalStop.call(e)
      ;(e as any)._stopped = true
    }

    // This is where the actual function calls occur.
    return value.map(fn => (e: Event) => !(e as any)._stopped && fn && fn(e))
  } else {
    return value
  }
}

And here we are, fully informed. Even though the official documentation and TypeScript might not explicitly endorse it, we've found a code segment that effectively allows us to pass event listeners using an array of function references.

There is the commit that introduced this functionality. It appears that at some point in the past, there might have been an intention to enable the capability of passing multiple listeners. However, as it stands now, this remains an undocumented feature.

Lastly, let's address the question we initially posed: Does Vue support multiple listeners? The answer hinges on your interpretation of "supports". To summarize:

We can invoke multiple functions using fn1(); fn2(), and there's a test for that.
We can also invoke them using fn1(), fn2().
We can pass it through an array if stored in a variable.

Alternatively, given the newfound knowledge, we can even call them like so:

<template>
  <button @click="[fn1, fn2].forEach((fn) => fn($event))">
    Click!
  </button>
</template>