Introducing Waku: The Minimal React Framework

Hi. First of all, thanks for this great opportunity to give a talk. I will talk about my recent project, Waku. It's an active project, so please note that what I talk about today might not be accurate in the future, but at least it is what it is now.

Before we dive into the main topic, let me introduce myself. My name is Daishi Kato, and I specialize in developing React libraries. You might already be using or at least have tried one of my libraries. Most of them are for React global states. If you haven't tried them before, I think it's a great chance to give them a shot.

Rustand is a state management library that is bare minimum and easy to learn. It's such a small library that I actually wondered if it was worth being a library. Nevertheless, it's widely used now.

Jotai is another state management library. It abstracts states as atoms. Atoms are definitions of states. With atom abstraction, we can define state logic. It's very handy. And the ecosystem is growing, too.

The third one is called Valisio. It enables a normal JavaScript object to be a React state. Usually, React state has to be immutable. But a JavaScript object is mutable. To bridge the gap between immutability and mutability, Valisio uses proxies extensively. It works like magic. To compare the popularity of these libraries, let's quickly check the number of NPM downloads. As you can see, Rustand is by far the most popular library. Jotai and Valisio have room to get more attraction.

By the way, people sometimes ask me why I develop three similar libraries. It's a long story. But what I found interesting is that I can compare these similar libraries.

Not only can we compare the statistics, but we also get triple feedback. As you might expect, this results in triple the workload.

Well, that's enough for my introduction. Let's move on.

So, what is Waku? I started the project in March 2023. Waku is a React framework. It actually means framework in Japanese. Waku depends heavily on React Server Components, or RSC. Both in terms of the design and the implementation. Our current target is small to medium-sized projects. And we focus on delivering a faster developer experience.

Now, let's discuss a bit more in detail for each aspect. What exactly is a React framework? Honestly, I don't think I have the right answer to this question. But anyway, in the React docs they mention React should be used with a framework. And such a framework should provide capabilities like code splitting, routing, data fetching and generating HTML. Waku provides those capabilities. It supports code splitting. It does routing. We can fetch data. And generating HTML, also known as SSR, is supported. However, that doesn't mean we implement everything in a framework. The basic parts of those capabilities are already implemented by the React library. So, the framework's job is basically to make them available to developers.

Another big job of the framework is bundling. It's to generate the final output for production, which might vary depending on the cloud service used for deployment. I found bundling is tricky with RSC and SSR. To be honest, I don't think I fully understand every detail yet. Let's move on to the next topic, RSC. RSC. Waku is based on React components.

And it was my motivation to start developing a framework.

So, what does React components provide? As I mentioned, Waku uses the React library for some capabilities. Those capabilities are based on RSC. One good example is data fetching. RSC supports async components and we can fetch data at the component level. RSC also enables code splitting and routing to some extent. All those capabilities are good. But the biggest benefit of RSC, I suppose, is reusability. RSC is defined by React, and if frameworks follow the React, the RSC convention, the difference between the frameworks is not noticeable to developers. That means, if a developer creates a component with RSC, it works with different RSC frameworks without modifications. So, when it comes to RSC, using Waku doesn't result in lock-in. I think interoperability between different React frameworks would be wonderful, and I hope such a future will come.

Another aspect is developer experience. One of Waku's goals is to provide a fast experience. To this end, Waku takes advantage from VIT. VIT's dev server allows us to avoid bundling everything at one time. It lazily compiles things as needed. Waku and VIT take care of hot reload or hot module replacement. So, if you edit files, the result will be shown without manual reloading. Currently, hot reload is for server components, and hot module replacement is for client modules. Waku also cares about the learning curve. Our API design aims to be simple and minimal, so that developers feel comfortable. I wouldn't say it has reached the goal yet. There's plenty of room for improvements, and we should keep working for a better developer experience.

Waku aims to be minimal. Why is it so? There are two major thoughts behind it. The first one is, as I just said, about the learning curve. Learning a small thing would be easier than learning something bigger. The API should be small, and so is the implementation. I notice early adopters read the Waku code.

My belief is that the readability and understandability of the framework itself is important for wider adoption. The second one is about the ecosystem. We are a small team, and we can't implement all required features, so Waku takes a minimalist approach. We only provide a limited set of features, but make them extensible so that collaborators can build new features around the core features. Really, the goal is to grow the ecosystem.

Currently, Waku is under active development. We are working hard toward V1 alpha. At that point, we will have completed most RST features, and we will start exploring more on Waku-specific features. Version 0.20 already has basic features to build websites using a file-based router. It's well suited for blog-like websites. Version 0.21 will support server actions for more server-interactive websites. There still remain some issues with library compatibility that should be solved, and there are some more features requested for Waku. After those issues are resolved, I would like to explore a possibility to integrate a client state management library. My first target will be Jotai. Another trial would be developing an alternative router implementation that will support Waku-specific features to build websites. Another trial would be developing an alternative router implementation. That way, we can confirm that Waku is a router-agnostic framework. Of course, we will need to work on more stability. We may refactor for more maintainability, and to help grow the ecosystem. I hope to reach V1's table not too far in the future, but it requires help from the community, so any feedback and contributions are very welcome.

In the rest of the talk, I would like to walk you through how we can start a new Waku project. It is just to show how to use Waku. It's not about how Waku itself is implemented or how or what React Server Components are. If you are interested, please watch my previous talk, which I talked about the fundamentals of React Server Components. To create a new Waku project, run npm create-waku-at-latest. In addition to npm, we also support yarn and pnpm. After you run the create command, you will be asked for a project's name, which will be a folder name. The default value, Waku Projects, should work fine for the first time. After that, we move into the folder and run the npm install command. Then you are all set.

To develop your app, you want to start a dev server. Just run npm run dev in the project folder. By default, it will listen on port 3000. So you open localhost 3000 in your browser and see the running app. You can then modify files in the source folder. Most file changes are detected and the browser will hot reload. In some cases, you may need a manual reload or restarting the server. Feel free to report to us if such cases occur.

Developing a Waku app requires a basic understanding of React Server Components. You can learn it on the Waku website, as well as the React website. When you are done with developing your project, it's time to build it. The command is npm run build. Take some time, but once it's finished, the result is in the dist folder under your project. By the way, the reason it takes time is that we run the build process four times. I believe this can be improved and we plan to work on it in the near future.

Now what can we do with the build result? You can run the build result in production mode. Simply run npm start command and it will listen on port 8080. If you open localhost 8080, you will see app running exactly as you saw in the development mode. If you have a server somewhere that you can run Node.js, it's possible to upload the project folder and run your app on the server. Waku also supports building static sites. If all of your server components are static, the build result is basically a static site. It's located in dist slash public folder. To test it locally, you can run npx serve dist slash public. It will serve files in the folder which you can open in your browser. You can deploy the dist public folder to any hosting service and publish it as a static site. To mark a server component as static, you need to configure it explicitly. It's done by exporting the getConfig function. Notice that static sites doesn't mean no interactivity. We can still make them interactive with client components. Waku supports deploying on Vercel out of the box.

All you need is to run the Vercel command. This builds the project and deploys static files and the serverless function. The serverless function takes care of both RST and SSR. You can visit demo.waku.gg to see a demo app deployed on Vercel.

If your app is a static site, you can add the withVercel static option to your build command in package.json. And it will keep deploying a serverless function on Vercel. In addition to Vercel, Waku currently supports a variety of other cloud services to some extent, including Netlify, Cloud Fireworkers, DenoDeploy, PartyKit, and AWS Lambda. While we may add more options, I'm considering creating a plugin system to allow collaborators to extend support for additional cloud services easily.

As we approach the end of this talk, let's wrap up things. In this talk, I've explained the overview of Waku and how to get started with it. I hope this encourages you to give it a try. The first thing you want to do is visit waku.gg and learn some basic Waku basics. Once you are familiar with fundamentals, you can start developing a small project. I hope you will find it enjoyable. Given the scope of this talk, I have not explained the technical details of Waku. I plan to share them at some point, but meanwhile, you can follow my activity on GitHub. That's it. Thanks for your attention. I hope you enjoyed it.