How an RSC Framework Enables Server Actions

I'm Daisuke Kato, and I'm really excited to give a talk at React Advanced London for the first time. I'm an open source developer, and over the past few years I've developed several React libraries, including Zest and Jota and Valsio.

While still maintaining those projects, my latest work has been focused on creating a new React framework. So the title of my talk today is How an RST Framework Enables Server Actions. Wait, let me modify it. The title is How an RST Framework Enables Server Functions. That's a new term. In this talk, I'll share some insights that I've learned during development. Please keep in mind that what I present today might not be 100% accurate. With that said, let's get started.

The framework I'm developing is called Waku. It's a team project because developing a framework is complicated, and I cannot do it alone. Unlike my other projects, which are small, Waku is bigger and broader. This became possible only because of our collaborators. The project started about a year and a half ago, and when I started, my knowledge of implementing a React framework was literally zero. There have been many iterations with trial and error, and it's still continuing. One of the recent tasks was supporting server functions.

This talk is about server functions, but for the first part, I'll spend some time discussing React Server Components, or RSC. React 19 introduces several new features, but one of the most significant is RSC.

RSC stands for React Server Components, but when we say RSC, it often refers to the entire capability of running React on a server. So, RSC includes server components, server functions, and maybe more. One tricky thing is that RSC doesn't always require a runtime server. It can render several components at build time and generate static sites. So, RSC can even help with single page applications.

Technically, RSC's core capability is serialization, and it's provided by a React library, but to consume it, you need a framework or at least a bundler. Now, let's explore how server components work. Before server components existed, the concept was simple, as you know. Everything ran on the client. By the way, one of the strengths of React, as I see, is this intermediary representation, sometimes called the virtual DOM. Thanks to this, we can render a component multiple times before committing or apply certain extensions. Server components can be considered as one of those extensions.

Now, with server components, we have two types of components. Both are rendered separately and merged into a single representation. JSX elements are serialized into a JSON-like format and sent to the client. It's hard to show in this diagram, but the two rendering processes don't actually happen simultaneously. Because server components point to the client components, the rendering actually happens on the server at first. Once the client receives the JSX elements from the server, it renders the client components and merges the two results. So far, so good?

Let's see how this is implemented. I would like to explain the idea with code. Here, two code scenes basically represent client code and server code. They are pseudocode, but they are pretty close to the actual implementation in my framework. Let's look at the client code. CreateRoot is a function that should be familiar to most React users. On the other hand, createFromFetch is a new function from the React library and is typically used by frameworks. Now, on the server side, when it receives a request, the server renders the app component and creates a stream. This stream is called the RST payload that the client receives and renders. The key function here is renderToReadableStream.

I like to emphasize that this is without SSR or server-side rendering. Adding SSR is complicated, and it's not the scope of this talk, but one key takeaway is that RST is not tied to SSR. SSR is used only for the initial render, while all subsequent re-renders on the client happen without SSR but with RST. As you can see, the app component is a server component.

What gets interesting is when we start using client components. As you may know, a server component file can import a client component file. We distinguish this with useClientDirective. The server has to serialize the client component into the RST payload. The entire purpose of useClientDirective is to make it serializable, creating a client reference. A client reference is basically an identifier that points to the client component.

Let's briefly look at it. This diagram shows how a client reference is used conceptually. On the server side, a client component becomes a client reference and is encoded into an RST payload, which is then transferred to the client. The client finds the reference in the payload and retrieves the actual client component. Retrieving the actual client component is a framework job, and for now you can assume a client reference acts like a URL. Until now, our discussion was kind of conceptual. But in practice, how is a client reference actually created? The answer is code transformation. Let's see how these client components get transformed.

First, we need a special function called registerClientReference. This function is provided by one of the React libraries. Now, how do we use this function? We wrap the actual function with it, and return the result as client component. Two strings are passed to the function. The first represents the file, and the second is the name of the exported function. These strings are used to identify the client component. Technically, they can be anything as long as they can identify the exported function. As we just saw, to make server components and client components work, we need to transform user code. The framework sits between user code and the JS runtime, handling code transformation. This is one of the reasons why RST needs a framework or bundler. We need to transform our code before running, and the transformation differs between different runtimes. In the previous example, the user code was transformed to a server runtime.

But do we ever need to transform the code for the client runtime? Yes, server function may require it. Now let's talk about server functions quickly. The idea of server functions isn't very difficult. Basically, it allows the client component to call a function on the server. This also requires serialization, which isn't very surprising.

Well, I think that's pretty much it. So I've talked about server components and now server functions. How are they related? As it turns out, server functions and client components have something in common. They're both just functions, and they need to be serializable because they're trouble between the server and the client. Some identifiers are used to this serialization called references. The transformations are triggered by directives. On the other hand, there are some differences, one of which is that there are several ways to create server references. Whereas creating the client references basically have only one way to be created. Suppose we've already obtained a server reference.

Using it isn't complicated. We can pass it to the server and the server can identify the actual function to call. What's not so obvious here is how the client gets the server reference in the first place. Unlike a client reference, there are multiple ways to create a server reference. And this is why supporting server functions is a non-trivial task. What do we mean by multiple ways to create server references? For example, there are top-level user server and inline user server directives. Additionally, there are different ways to pass server references. In the rest of this talk, I'll discuss some typical cases and how a framework transforms user code for different situations. This is the first case, and I think it's the simplest. On the top, the server function file contains a top-level user server directive. And this file exposes a function named greet. On the bottom, the server component file imports the server function file and passes the greet function to a client component. If you're familiar with server functions, this should look pretty straightforward. But how does it actually work? How is the server function file transformed? Let's take a look at how a framework transforms this user code. This is the same code we just saw. First of all, we no longer need the directive, since its purpose is to tell the framework that the code needs to be transformed.

Now that we are transforming it, the directive can be removed. We import the register server reference function. It's provided by React, but which library to import from depends on the framework. So in this snippet, we wrap it as dot, dot, dot.

Now let's see how we use this function. As you can see, we simply call this function at the end. This will register a server reference for the greet function. Take a look at the two string parameters passed to the register server reference. As we learned with client references, those are to identify the registered function. In this case, they are the file path and the function name. But as I said, they can be anything, technically speaking.

This transformation logic is rather simple and actually is provided by one of the React libraries. So supporting this pattern is fairly easy. I wish this would be the only pattern we need to support, but it's not. Let's learn some other cases.

The second case is when you have the inline use server directive in the server component. Let's look at code. In the previous example, the greet function was imported from a separate file. But here, it's an inline function directory in the JSX. Let's check out the use server directive, which triggers the transformation. First, we import register server reference like before. Second, we have to lift up the inline function to the module level. Third, we register server reference, adding the two string parameters as an identifier. Finally, the function has to be exported from the module because it needs to be callable when the server received the request. Are you following? Let's move on to the next case.

In this example, we have a variable inside the component. For simplicity, it's just a random number. This random number is used both in the JSX string and in the greet function. The greet function has a use server directive, meaning it's a server function that needs to be transformed. The tricky part here is that every time the app component renders, a new random number is generated. Anyway, let's see how it goes. As always, we begin by importing register server reference. Just like the previous example, we lift up the inline function to the top. But now, the closure variable, rand, is gone. So what should we do? As you can see, we can use the bind method to attach such variables, and the server function will receive them as arguments. One note here is that I'm not entirely confident with this approach, but for now, this is how it's working. Moving on to another use case.

So here's a new use case. We have two files. One is a server function with a use server directive, and the other is a client component with a use client directive. In this case, the client file directly imports the server file. This might seem straightforward from the user's perspective, but it's actually quite tricky. Let's take a look at how this is transformed. This is a server file, which is being imported from a client file. In the first line, we import create server reference from a React library.

You notice it's different from register server reference we've been using. This is a client side version. In the second line, we import call server RSC, which is a framework specific function from work with last client in this case. We completely replace the function on the call create server reference. The first argument is a string identifier, and the second argument is the framework function. As you can see, this requires tighter integration with the framework.

We've already seen many cases, but there's one more I'd like to show you. This example is a bit different from the previous ones. So, in fact, any function can have an inline use server directive. In this case, it's a function inside an object, which is then exported. Let's see how this gets transformed. First, we import register server reference. And it's done. The function is hoisted and exported with register server reference. And in the original object, the function is replaced with the exported one. To make this work, we need to look through all exported objects deeply until we find inline use server directives. Once found, the rest is the same as before. But this feels like a very costly task. I wonder if we can optimize this somehow.

All right. We've covered through various cases. Did any of them catch your attention? Here's a list of cases we've covered. Do you remember that there are five different cases? I hope this covers enough, but the list may grow. And there might be some cases that requires further work. The point of this talk was to show that while it's not trivial for a framework to enable server functions, it's certainly doable. This is the same diagram that I showed earlier. The framework's job is to transform user code for different runtimes, like the client or server. This is how an RST framework enables server components and server functions. This is what I wanted to share in this talk.

This is what I wanted to share in this talk. I hope it's insightful for you. Our framework, Waku, implements everything I've talked about today. Supporting server function is a challenging task, but we've done it. And Waku now supports them. If you are interested, feel free to check it out at waku.gg.

And with that, this finishes my talk. I'm Daishikato. You can find links to reach out at daishikato.com. Thanks for listening and watching. Feel free to reach out to me for more discussion. See ya!

Thank you for your talk. Daishikato, you have been a very busy person with maintaining all of these libraries. Can you tell us a little bit about how you, after already working on so many things, thought, I need Waku now, and what you were trying to accomplish? Yes. Thanks to some collaborators, the three state management libraries are kind of maintained well. And basically, it's kind of done, so I just need to keep some stuff maintained. So it was a good start to start a new project, Waku, which is a React framework. But I didn't know it was that hard when I started. Yeah, it's pretty challenging. Look, we don't do it because it's easy. We do it because we thought it would be easy. Am I right?

Yeah. So let's get into the questions from the audience. Do you think supporting used server in so many different ways was a good decision from React in terms of implementation complexity versus user value? Good question. I'm not sure if I or a right person to answer this, because it's designed by React. But as long as it's clearly specified with a spec, I think it's a good move because obviously it's good for the developer experience. So, yeah, basically, I agree with this decision. Fair enough. React server components adds a lot of complexity and a lot of abstractions. Do you think the tradeoff is worth it? Sure.

And we have a discussion later, right? Yeah. And why we're not using suspense enough? We already answered that one.

As a consumer of Waku, is all I need to worry about where I put my used client and used server directives? Yeah, that's true. But it depends on the question. It requires to have a good mental model to design what should be server components, what should be client. So it's not just adding directives, but it has to be designed well.

Yeah. Mark. Thanks, Mark. Mark asked, how much time, effort, trial and error did it take to determine those five cases that you talked about? Was there any documentation from React that helped or was it all experiments? Yeah, so that's a good question because there is no docs. So I learned through the behavior and some of my colleagues helped me. And actually, it took more time before working on this because I didn't know anything about React server components. And it takes more time than this server function capability.

Do you feel like you got it now? Yeah. You're an expert. If you have any server component questions, this is your guy. This is an interesting one. Do you feel like Waku is a long term project for you? Yeah, it's going to be a long term project. You heard it here first. It'll be around, so check it out.

I'm going to check that. Does Waku build on top of any of your other projects or inspired by? It's not built on my other project. And it's based on Vite and Hono. But the idea is pretty close to my other project, Jotai. Because it tries to be minimal and it provides some building blocks. So I took the idea because I thought it was successful. So I learned it from it.

How do you, sort of, do you get any feedback or do you have any beta testers that help you test out the API? I actually need more beta testers. There were hundreds of developers here that could check it out. We are running out of time, but can you remind everyone where to find you on the internet and Waku? Yeah, I have a contact site that was shown on the website. I mean, the slide, it's daishikato.com. You can find all those links to reach out to me. Thank you for your time and thank you for your talk. Give it up again. Thank you.