{"id":12649,"library":"waku","title":"Waku: The Minimal React Framework","description":"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`.","status":"active","version":"1.0.0-alpha.7","language":"javascript","source_language":"en","source_url":"https://github.com/wakujs/waku","tags":["javascript","react","minimal","framework"],"install":[{"cmd":"npm install waku","lang":"bash","label":"npm"},{"cmd":"yarn add waku","lang":"bash","label":"yarn"},{"cmd":"pnpm add waku","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required peer dependency for React components and rendering.","package":"react","optional":false},{"reason":"Required peer dependency for client-side ReactDOM operations.","package":"react-dom","optional":false},{"reason":"Required peer dependency for React Server Components runtime and serialization.","package":"react-server-dom-webpack","optional":false}],"imports":[{"note":"Used in `waku.config.ts` for project configuration. Waku is primarily an ESM package.","wrong":"const defineConfig = require('waku').defineConfig;","symbol":"defineConfig","correct":"import { defineConfig } from 'waku';"},{"note":"Client component for defining application routes. Typically used in `src/app.tsx` or similar component trees.","symbol":"Router","correct":"import { Router } from 'waku/router';"},{"note":"Client component for navigation within the Waku application, similar to `` but with client-side routing capabilities.","symbol":"Link","correct":"import { Link } from 'waku/router';"},{"note":"For programmatic starting of the development server, though the `waku dev` CLI command is more commonly used. Waku is ESM-only.","wrong":"require('waku').startDevServer;","symbol":"startDevServer","correct":"import { startDevServer } from 'waku';"}],"quickstart":{"code":"import { defineConfig } from 'waku';\n\nexport default defineConfig({\n rootDir: 'src',\n ssr: true,\n // Add custom Vite config if needed\n // vite: () => ({\n // plugins: [],\n // }),\n});\n\n// src/app.tsx\nimport { Router, Link } from 'waku/router';\n\nexport const App = () => (\n \n \n {/* Router handles rendering content based on current path */}\n \n);\n\n// src/pages/counter.tsx\n'use client';\n\nimport { useState } from 'react';\n\nexport const Counter = () => {\n const [count, setCount] = useState(0);\n\n return (\n <>\n

Client Counter

\n
Count: {count}
\n \n \n );\n};\n\n// To run this example, create a new Waku project:\n// npm create waku@latest my-app\n// cd my-app\n// npm install\n// npm run dev","lang":"typescript","description":"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."},"warnings":[{"fix":"Regularly review release notes and test thoroughly when upgrading alpha versions. Refer to the official migration guides for specific changes.","message":"Waku 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.","severity":"gotcha","affected_versions":">=1.0.0-alpha.0"},{"fix":"Update your `wrangler.jsonc` file's `main` property to `\"./src/wa\"` as shown in the v1.0.0-alpha.4 migration guide.","message":"The main entry point for Cloudflare Workers deployments changed from `./dist/server/serve-cloudflare.js` to `./src/wa`. This requires updating your `wrangler.jsonc` configuration.","severity":"breaking","affected_versions":">=1.0.0-alpha.4"},{"fix":"Consult the `v1.0.0-alpha.3` release notes for the new option name and update your configuration file accordingly.","message":"The `renderHtml` option, likely used in `waku.config.ts` for custom HTML rendering, was renamed. This affects projects using custom HTML configurations.","severity":"breaking","affected_versions":">=1.0.0-alpha.3"},{"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/`.","message":"The 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.","severity":"breaking","affected_versions":">=1.0.0-alpha.1"},{"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.","message":"Waku has strict Node.js engine requirements. Running with an unsupported Node.js version will prevent the application from starting or building correctly.","severity":"gotcha","affected_versions":">=1.0.0-alpha.0"},{"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`.","message":"Waku 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.","severity":"gotcha","affected_versions":">=1.0.0-alpha.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure `'use client';` or `'use server';` is the absolute first line of code in the file, including comments or blank lines.","cause":"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.","error":"Error: The 'use client' directive must be at the top of the file."},{"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.","cause":"Waku is distributed as an ES Module (ESM). This error occurs when attempting to `require()` Waku or a related package from a CommonJS context.","error":"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."},{"fix":"Install the missing peer dependency: `npm install react-server-dom-webpack@~19.2.4` (adjust the version to match Waku's `peerDependencies`).","cause":"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.","error":"Module not found: Error: Can't resolve 'react-server-dom-webpack' in '...'"},{"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.","cause":"The project's Node.js environment does not meet the specified engine requirements for Waku.","error":"Your current Node.js version is X. Waku requires Node.js ^24.0.0 || ^22.12.0 || ^20.19.0."}],"ecosystem":"npm"}