Waku: A minimal React framework built on server components

Server components at the architectural center

Waku is a React framework that places server components at the architectural center. It is built for marketing sites, headless commerce, and full-stack web apps of any size. The design philosophy is that Waku keeps its framework surface minimal and composes with ecosystem libraries, while heavier frameworks like Next.js own more of those concerns for you. Whether Waku fits is about the architecture you want, not the size of your project. Waku provides routing, rendering modes (static or server-side), and build tooling. Everything else (authentication, database drivers, image optimization, payment processing) is delegated to library choices you make. This means Waku teams need to make more architecture decisions upfront, but gain full control over their stack.

Server components as the foundation

Waku is built on React 19 server components. A server component is an async React component that runs exclusively on the server. It can access the file system, database, and import heavy dependencies without adding to the client bundle. Server components have no state, no event handlers, and no access to browser APIs. When you need interactivity, you create a client component and mark it with 'use client' at the top of the file. When a server component imports a client component, it creates a server-client boundary. All components imported below this boundary run in the browser as well as on the server. The README provides a concrete pattern: a root _layout.tsx server component that imports a Providers client component, and Providers wraps its children (which are server components) in a client-side context provider like Jotai. This composition pattern enables state management and context across the server-client boundary.

The README emphasizes: do not be intimidated by the 'use client' directive. Once you understand the pattern, flexibly moving server-client boundaries with a single line of code is simpler than maintaining separate backend and frontend codebases. Server components can import client components and pass them server components as children, letting you compose providers and layouts that work across the boundary. This flexibility enables you to refactor your app's rendering model as needs change without rewriting separate backend and frontend services.

Creating a new Waku project and running commands

Start a new Waku project with:

npm create waku@latest

This scaffolds a project with the default Waku starter. Three commands are available:

waku dev
waku build
waku start

waku dev starts the local development server. waku build generates a production build. waku start serves the production build locally.

Node.js version requirement is ^26.0.0 or ^24.0.0 or ^22.15.0. Older versions will not work. For a guided path, start with the Quick Start guide and continue with the Learn series on waku.gg/guides, which builds a small app step by step.

File-based routing and rendering modes

Waku provides a minimal file-based pages router in the ./src/pages directory. Layouts and pages are React components that export a default component and a getConfig function specifying render mode. The framework supports static prerendering (SSG) and server-side rendering (SSR) options for both layouts and pages, including all of their server and client components. Note that SSR is a distinct concept from RSC (React server components). Both can be used together: a page can be server-side rendered at request time, and within that rendered page, components use server and client boundaries to determine where logic executes. The `getConfig` export returns a config object with a `render` property set to 'static' for SSG or omitted for SSR.

The low-level programmatic routing API is also available in the repository for teams that prefer to define routes in code instead of the file system. A `create-pages` API provides this option and is documented in the package. The monorepo structure in `packages/` contains the core framework, with examples in separate template packages.

Shared components across server and client

Simple React components that follow the rules for both server and client can be imported into either without creating a boundary. A shared component is a pure function that returns JSX, with no state, no effects, and no browser API calls. The README provides an example: a Headline component that wraps its children in an h3 tag can be used anywhere. Shared components are useful for presentational logic that both server and client need. As your app grows, you will develop a library of these components. They keep your codebase DRY and let you migrate parts of your app between server and client rendering as needs change. The distinction between server, client, and shared components becomes clearer as you write more code; the React Server Components RFC documentation linked in the README provides more examples and clarifications.

Learning curve and framework scope

The README acknowledges that modern React rendering introduces a learning curve. Understanding server components, their constraints, and the rules for client boundaries takes time. However, the README also states that the patterns are powerful: server components enable full-stack composability that was not possible before. Even light optimization towards server components reduces client bundle size compared to a fully client-rendered React app. The framework documentation links to external resources like Making Sense of React Server Components and The Two Reacts to help developers build mental models.

Waku intentionally keeps framework surface minimal. This creates more decisions for you to make: how to handle authentication, where to store data, which CSS solution to use, how to deploy. These decisions are not a flaw; they reflect the design choice to let teams own their architecture. Future versions of Waku may provide optional APIs to abstract some complexity away, but the current version prioritizes transparency and flexibility over convention. The development build runs via `pnpm dev:cli` in monorepo mode, with TypeScript type checking through the `tsc` command. Tests use Playwright for end-to-end testing and vitest for unit tests.

When Waku is not the right choice

Waku's minimalism is a strength and a limitation. If your project needs built-in features like authentication libraries, image optimization, API route handlers, or automatic edge function deployment, another framework like Next.js will move faster. If your team is not ready to reason about server components and component boundaries, the learning curve will slow you down. Waku is not a batteries-included framework. You bring the batteries. If you prefer frameworks that provide strong opinions and handle more concerns, Waku's flexibility is a liability rather than an asset.

Editorial conclusion

Waku suits teams building full-stack React applications who prefer to compose a stack from libraries rather than adopt a monolithic framework. It is most useful when your team understands React server components and accepts the learning curve of marking component boundaries with use client. It is less suitable for projects where framework features like authentication, image optimization or API routes are requirements. Start by running npm create waku@latest and follow the Quick Start guide on waku.gg. Verify that your Node.js version matches ^26.0.0 or ^24.0.0 or ^22.15.0; older versions will not work.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. wakujs/waku on GitHub