waku

library0.43.0jsnpmunverified

Waku is a minimal React framework designed for building performant web applications with a focus on React Server Components (RSC) and React 19 features. Currently in its v1.0.0-alpha.7 release, it is under active development with frequent alpha releases that may introduce breaking changes, particularly in adapters and internal APIs. Waku is optimized for marketing sites, blogs, headless commerce, and web apps where a lightweight footprint and full-stack React composability are key differentiators. Unlike heavier frameworks, it emphasizes a lean approach, prioritizing a fun developer experience with modern React paradigms. It supports all the latest React 19 features, including server components and actions, aiming for smaller client bundle sizes by leveraging server-side rendering extensively. It requires Node.js `^24.0.0`, `^22.12.0`, or `^20.19.0`.

web-framework

npm install waku

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · WAKU

waku

web-frameworkjavascriptv0.43.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

defineConfig

✓ import { defineConfig } from 'waku';

✗ const defineConfig = require('waku').defineConfig;

Used in `waku.config.ts` for project configuration. Waku is primarily an ESM package.

Router

✓ import { Router } from 'waku/router';

Client component for defining application routes. Typically used in `src/app.tsx` or similar component trees.

Link

✓ import { Link } from 'waku/router';

Client component for navigation within the Waku application, similar to `<a>` but with client-side routing capabilities.

startDevServer

✓ import { startDevServer } from 'waku';

✗ require('waku').startDevServer;

For programmatic starting of the development server, though the `waku dev` CLI command is more commonly used. Waku is ESM-only.

Sets up a basic Waku project with a configuration file, a main application router, and a client-side counter component to demonstrate interactivity and routing.

import { defineConfig } from 'waku'; export default defineConfig({ rootDir: 'src', ssr: true, // Add custom Vite config if needed // vite: () => ({ // plugins: [], // }), }); // src/app.tsx import { Router, Link } from 'waku/router'; export const App = () => ( <Router> <nav> <Link to="/">Home</Link> <Link to="/counter">Counter</Link> </nav> {/* Router handles rendering content based on current path */} </Router> ); // src/pages/counter.tsx 'use client'; import { useState } from 'react'; export const Counter = () => { const [count, setCount] = useState(0); return ( <> <h1>Client Counter</h1> <div>Count: {count}</div> <button onClick={() => setCount((c) => c + 1)}>Increment</button> </> ); }; // To run this example, create a new Waku project: // npm create waku@latest my-app // cd my-app // npm install // npm run dev

waku --version

Debug

Known issues

gotchaWaku is currently in an alpha state (v1.0.0-alpha.7). While public APIs are stated as stable, internal implementation details, adapters, and behavioral aspects may still undergo changes, potentially breaking existing setups between minor alpha versions. It is recommended for non-production projects only.

fix

Regularly review release notes and test thoroughly when upgrading alpha versions. Refer to the official migration guides for specific changes.

affects: >=1.0.0-alpha.0

breakingThe main entry point for Cloudflare Workers deployments changed from `./dist/server/serve-cloudflare.js` to `./src/wa`. This requires updating your `wrangler.jsonc` configuration.

fix

Update your `wrangler.jsonc` file's `main` property to `"./src/wa"` as shown in the v1.0.0-alpha.4 migration guide.

affects: >=1.0.0-alpha.4

breakingThe `renderHtml` option, likely used in `waku.config.ts` for custom HTML rendering, was renamed. This affects projects using custom HTML configurations.

fix

Consult the `v1.0.0-alpha.3` release notes for the new option name and update your configuration file accordingly.

affects: >=1.0.0-alpha.3

breakingThe directory for file-based API routes changed from `./src/pages/api/` to `./src/pages/_api/`. The `_api/` segment is stripped from the URL path by default.

fix

Move your API route files from `./src/pages/api/` to `./src/pages/_api/`. To preserve the `api/` prefix in URLs, move them to `./src/pages/_api/api/`.

affects: >=1.0.0-alpha.1

gotchaWaku has strict Node.js engine requirements. Running with an unsupported Node.js version will prevent the application from starting or building correctly.

fix

Ensure your Node.js version is `^24.0.0` or `^22.12.0` or `^20.19.0`. Use a Node.js version manager like `nvm` to switch if necessary.

affects: >=1.0.0-alpha.0

gotchaWaku requires `react`, `react-dom`, and `react-server-dom-webpack` as peer dependencies at specific versions (e.g., `~19.2.4`). Mismatched or missing peer dependencies can lead to runtime errors, especially with React Server Components.

fix

Install the exact peer dependency versions specified by Waku in your project: `npm install react@~19.2.4 react-dom@~19.2.4 react-server-dom-webpack@~19.2.4`.

affects: >=1.0.0-alpha.0

Errors

Common errors & fixes

Error: The 'use client' directive must be at the top of the file.

The 'use client' or 'use server' directives define server-client boundaries and must be the very first statement in a file, before any imports or code.

fix

Ensure `'use client';` or `'use server';` is the absolute first line of code in the file, including comments or blank lines.

ERR_REQUIRE_ESM: require() of ES Module X from Y not supported. Instead change the require of X to a dynamic import() which is available in all CommonJS modules.

Waku is distributed as an ES Module (ESM). This error occurs when attempting to `require()` Waku or a related package from a CommonJS context.

fix

Migrate your project to use ES Modules (e.g., set `"type": "module"` in `package.json` and use `import` statements), or use dynamic `import()` for specific modules that are exclusively ESM.

Module not found: Error: Can't resolve 'react-server-dom-webpack' in '...'

The `react-server-dom-webpack` package is a required peer dependency for Waku's React Server Components functionality and is missing or not installed correctly.

fix

Install the missing peer dependency: `npm install react-server-dom-webpack@~19.2.4` (adjust the version to match Waku's `peerDependencies`).

Your current Node.js version is X. Waku requires Node.js ^24.0.0 || ^22.12.0 || ^20.19.0.

The project's Node.js environment does not meet the specified engine requirements for Waku.

fix

Upgrade or switch your Node.js version to one within the supported range (e.g., Node.js 20.x, 22.x, or 24.x) using `nvm` or similar tools.

Upgrade

Version history

0.43.0latest on npm

Audit

Dependencies

reactrequiredRequired peer dependency for React components and rendering.

react-domrequiredRequired peer dependency for client-side ReactDOM operations.

react-server-dom-webpackrequiredRequired peer dependency for React Server Components runtime and serialization.

Agent activity

16 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/wakujs/waku ↗

packagehttps://www.npmjs.com/package/waku ↗

homepagehttps://waku.gg ↗