⛩️ The minimal React framework

visit waku.gg or npm create waku@latest

Introduction

Waku (wah-ku) or わく is the minimal React framework. It's lightweight and designed for a fun developer experience, yet supports all the latest React 19 features like server components and actions. Built for marketing sites, headless commerce, and full-stack web apps, small or large. Whether Waku fits is about the architecture you want, not the size of your project: Waku keeps its framework surface minimal and composes with ecosystem libraries, while heavier frameworks own more of those concerns for you.

Getting started

Start a new Waku project with the create command for your preferred package manager. It will scaffold a new project with our default Waku starter.

npm create waku@latest

Commands

• waku dev to start the local development server
• waku build to generate a production build
• waku start to serve the production build locally

Node.js version requirement: ^26.0.0 or ^24.0.0 or ^22.15.0

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.

Rendering

While there's a bit of a learning curve to modern React rendering, it introduces powerful new patterns of full-stack composability that are only possible with the advent of server components.

So please don't be intimidated by the 'use client' directive! Once you get the hang of it, you'll appreciate how awesome it is to flexibly move server-client boundaries with a single line of code as your full-stack React codebase evolves over time. It's way simpler than maintaining separate codebases for your backend and frontend.

And please don't fret about client components! Even if you only lightly optimize towards server components, your client bundle size will be smaller than that of a fully client-rendered React app.

Future versions of Waku may provide additional opt-in APIs to abstract some of the complexity away for an improved developer experience.

Server components

Server components can be made async and can securely perform server-side logic and data fetching. Feel free to access the local file-system and import heavy dependencies since they aren't included in the client bundle. They have no state, interactivity, or access to browser APIs since they run exclusively on the server.

// server component
import db from 'some-db';
import { Gallery } from '../components/gallery';
export const Store = async () => {
  const products = await db.query('SELECT * FROM products');
  return <Gallery products={products} />;
};

Client components

A 'use client' directive placed at the top of a file will create a server-client boundary when imported into a server component. All components imported below the boundary will be hydrated to run in the browser as well. They can use all traditional React features such as state, effects, and event handlers.

// client component
'use client';
import { useState } from 'react';
export const Counter = () => {
  const [count, setCount] = useState(0);
  return (
    <>
      <div>Count: {count}</div>
      <button onClick={() => setCount((c) => c + 1)}>Increment</button>
    </>
  );
};

Shared components

Simple React components that meet all of the rules of both server and client components can be imported into either server or client components without affecting the server-client boundary.

// shared component
export const Headline = ({ children }) => {
  return <h3>{children}</h3>;
};

Weaving patterns

Server components can import client components and doing so will create a server-client boundary. Client components cannot import server components, but they can accept server components as props such as children. For example, you may want to add global context providers this way.

// ./src/pages/_layout.tsx
import { Providers } from '../components/providers';
export default async function RootLayout({ children }) {
  return (
    <Providers>
      <main>{children}</main>
    </Providers>
  );
}
export const getConfig = async () => {
  return {
    render: 'static',
  } as const;
};

// ./src/components/providers.tsx
'use client';
import { Provider } from 'jotai';
export const Providers = ({ children }) => {
  return <Provider>{children}</Provider>;
};

Server-side rendering

Waku provides 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.

tl;dr:

Each layout and page in Waku is composed of a React component hierarchy.

It begins with a server component at the top of the tree. Then at points down the hierarchy, you'll eventually import a component that needs client component APIs. Mark this file with a 'use client' directive at the top. When imported into a server component, it will create a server-client boundary. Below this point, all imported components are hydrated and will run in the browser as well.

Server components can be rendered below this boundary, but only via composition (e.g., children props). Together they form a new "React server" layer that runs before the traditional "React client" layer with which you're already familiar.

Client components are still server-side rendered as SSR is separate from RSC. Please see the linked diagrams for a helpful visual.

Further reading

To learn more about the modern React architecture, we recommend Making Sense of React Server Components and The Two Reacts.

Routing

Waku provides a minimal file-based "pages router" experience built for the server components era.

Its underlying low-level API is also available for those that prefer programmatic routing. This documentation covers file-based routing since many React developers prefer it, but please feel free to try both and see which you like more!

Overview

The directory for file-based routing in Waku projects is ./src/pages.

Layouts and pages can be created by making a new file with two exports: a default function for the React component and a named getConfig function that returns a configuration object to specify the render method and other options.

Waku currently supports two rendering options:

• 'static' for static prerendering (SSG)

• 'dynamic' for server-side rendering (SSR)

Layouts, pages, and slices are all static by default, while api handlers default to dynamic.

For example, you can statically prerender a global header and footer in the root layout at build time, but dynamically render the rest of a home page at request time for personalized user experiences.

// ./src/pages/_layout.tsx
import '../styles.css';
import { Providers } from '../components/providers';
import { Header } from '../components/header';
import { Footer } from '../components/footer';
// Create root layout
export default async function RootLayout({ children }) {
  return (
    <Providers>
      <Header />
      <main>{children}</main>
      <Footer />
    </Providers>
  );
}
export const getConfig = async () => {
  return {
    render: 'static',
  } as const;
};

// ./src/pages/index.tsx
// Create home page
export default async function HomePage() {
  const data = await getData();
  return (
    <>
      <h1>{data.title}</h1>
      <div>{data.content}</div>
    </>
  );
}
const getData = async () => {
  /* ... */
};
export const getConfig = async () => {
  return {
    render: 'dynamic',
  } as const;
};

Pages

Pages render a single route, segment route, or catch-all route based on the file system path (conventions below). All page components automatically receive two props related to the rendered route: path (string) and query (string).

Single routes

Pages can be rendered as a single route (e.g., about.tsx or blog/index.tsx).

// ./src/pages/about.tsx
// Create about page
export default async function AboutPage() {
  return <>{/* ...*/}</>;
}
export const getConfig = async () => {
  return {
    render: 'static',
  } as const;
};

// ./src/pages/blog/index.tsx
// Create blog index page
export default async function BlogIndexPage() {
  return <>{/* ...*/}</>;
}
export const getConfig = async () => {
  return {
    render: 'static',
  } as const;
};

Segment routes

Segment routes (e.g., [slug].tsx or [slug]/index.tsx) are marked with brackets.

The rendered React component automatically receives a prop named by the segment (e.g., slug) with the value of the rendered segment (e.g., 'introducing-waku').

If statically prerendering a segment route at build time, a staticPaths array must also be provided.

// ./src/pages/blog/[slug].tsx
import type { PageProps } from 'waku/router';
// Create blog article pages
export default async function BlogArticlePage({
  slug,
}: PageProps<'/blog/[slug]'>) {
  const data = await getData(slug);
  return <>{/* ...*/}</>;
}
const getData = async (slug) => {
  /* ... */
};
export const getConfig = async () => {
  return {
    render: 'static',
    staticPaths: ['introducing-waku', 'introducing-pages-router'],
  } as const;
};

// ./src/pages/shop/[category].tsx
import type { PageProps } from 'waku/router';
// Create product category pages
export default async function ProductCategoryPage({
  category,
}: PageProps<'/shop/[category]'>) {
  const data = await getData(category);
  return <>{/* ...*/}</>;
}
const getData = async (category) => {
  /* ... */
};
export const getConfig = async () => {
  return {
    render: 'dynamic',
  } as const;
};

Static paths (or other config values) can also be generated programmatically.

// ./src/pages/blog/[slug].tsx
import type { PageProps } from 'waku/router';
// Create blog article pages
export default async function BlogArticlePage({
  slug,
}: PageProps<'/blog/[slug]'>) {
  const data = await getData(slug);
  return <>{/* ...*/}</>;
}
const getData = async (slug) => {
  /* ... */
};
export const getConfig = async () => {
  const staticPaths = await getStaticPaths();
  return {
    render: 'static',
    staticPaths,
  } as const;
};
const getStaticPaths = async () => {
  /* ... */
};

Nested segment routes

Routes can contain multiple segments (e.g., /shop/[category]/[product]) by creating folders with brackets as well.

// ./src/pages/shop/[category]/[product].tsx
import type { PageProps } from 'waku/router';
// Create product category pages
export default async function ProductDetailPage({
  category,
  product,
}: PageProps<'/shop/[category]/[product]'>) {
  return <>{/* ...*/}</>;
}
export const getConfig = async () => {
  return {
    render: 'dynamic',
  } as const;
};

For static prerendering of nested segment routes, the staticPaths array is instead composed of ordered arrays.

// ./src/pages/shop/[category]/[product].tsx
import type { PageProps } from 'waku/router';
// Create product detail pages
export default async function ProductDetailPage({
  category,
  product,
}: PageProps<'/shop/[category]/[product]'>) {
  return <>{/* ...*/}</>;
}
export const getConfig = async () => {
  return {
    render: 'static',
    staticPaths: [
      ['same-category', 'some-product'],
      ['same-category', 'another-product'],
    ],
  } as const;
};

Catch-all routes

Catch-all or "wildcard" segment routes (e.g., /app/[...catchAll]) are marked with an ellipsis before the name and have indefinite segments.

Wildcard routes receive a prop with segment values as an ordered array. For example, the /app/profile/settings route would receive a catchAll prop with the value ['profile', 'settings']. These values can then be used to determine what to render in the component.

// ./src/pages/app/[...catchAll].tsx
import type { PageProps } from 'waku/router';
// Create dashboard page
export default async function DashboardPage({
  catchAll,
}: PageProps<'/app/[...catchAll]'>) {
  return <>{/* ...*/}</>;
}
export const getConfig = async () => {
  return {
    render: 'dynamic',
  } as const;
};

Group routes

Group routes allow you to organize routes into logical groups without affecting the URL structure. They're created by wrapping directory names in parentheses (e.g., (group)). This is particularly useful for sharing layouts across multiple routes while keeping the URL clean.

For example, you might want a home page at / that doesn't use a shared layout, but all other routes should share a common layout. This can be achieved by grouping those routes:

├── (main)
│ ├── _layout.tsx
│ ├── about.tsx
│ └── contact.tsx
└── index.tsx

In this structure, /about and /contact will use the layout from (main)/_layout.tsx, but / (from index.tsx) will not.

// ./src/pages/(main)/_layout.tsx
import { Header } from '../../components/header';
import { Footer } from '../../components/footer';
// Create shared layout for main pages
export default async function MainLayout({ children }) {
  return (
    <>
      <Header />
      <main>{children}</main>
      <Footer />
    </>
  );
}
export const getConfig = async () => {
  return {
    render: 'static',
  } as const;
};

// ./src/pages/(main)/about.tsx
export default async function AboutPage() {
  return <h1>About Us</h1>;
}
export const getConfig = async () => {
  return {
    render: 'static',
  } as const;
};

Group routes can be nested to create complex layout compositions. For instance, you could have a static layout at the group level and a dynamic layout nested within:

(main)
├── (dynamic)
│ ├── _layout.tsx # dynamic layout
│ ├── dashboard.tsx
│ └── profile.tsx
└── _layout.tsx # static layout

This allows for fine-grained control over rendering modes - some work can be done at build time (static) while other work happens at runtime (dynamic).

// ./src/pages/(main)/_layout.tsx
// Static layout - runs at build time
export default async function MainLayout({ children }) {
  return <div className="main-container">{children}</div>;
}
export const getConfig = async () => {
  return {
    render: 'static',
  } as const;
};

// ./src/pages/(main)/(dynamic)/_layout.tsx
// Dynamic layout - runs at request time
export default async function DynamicLayout({ children }) {
  const userData = await fetchUserData(); // Dynamic data fetching
  return (
    <div className="dynamic-container">
      <UserContext.Provider value={userData}>{children}</UserContext.Provider>
    </div>
  );
}
export const getConfig = async () => {
  return {
    render: 'dynamic',
  } as const;
};

Group routes are especially powerful for organizing complex applications where different sections need different layouts, state management, or data requirements while maintaining clean URLs.

Ignored routes

The following directories are ignored by the router:

• _actions
• _components
• _hooks

All files inside these directories are excluded from routing.

For instance, in the case below, pages/about.tsx is routed to /about, but files like _components/header.tsx are not routed anywhere.

pages/
├── about.tsx
├── _components/
│   ├── header.tsx   // 👈🏼 ignored
│   ├── footer.tsx   // 👈🏼 ignored
│   ├── ...          // 👈🏼 ignored

Router paths type safety

Import PageProps from waku/router for type-safe access to route parameters (as shown in the examples above). The type provides path, query, and all segment parameters:

PageProps<'/blog/[slug]'>;
// => { path: string; slug: string; query: string }
PageProps<'/shop/[category]/[product]'>;
// => { path: string; category: string; product: string; query: string }

Layouts

Layouts are created with a special _layout.tsx file name and wrap the entire route and its descendants. They must accept a children prop of type ReactNode. While not required, you will typically want at least a root layout.

Root layout

The root layout placed at ./pages/_layout.tsx is especially useful. It can be used for setting global styles, global metadata, global providers, global data, and global components, such as a header and footer.

// ./src/pages/_layout.tsx
import '../styles.css';
import { Providers } from '../components/providers';
import { Header } from '../components/header';
import { Footer } from '../components/footer';
// Create root layout
export default async function RootLayout({ children }) {
  return (
    <Providers>
      <link rel="icon" type="image/png" href="/images/favicon.png" />
      <meta property="og:image" content="/images/opengraph.png" />
      <Header />
      <main>{children}</main>
      <Footer />
    </Providers>
  );
}
export const getConfig = async () => {
  return {
    render: 'static',
  } as const;
};

// ./src/components/providers.tsx
'use client';
import { createStore, Provider } from 'jotai';
const store = createStore();
export const Providers = ({ children }) => {
  return <Provider store={store}>{children}</Provider>;
};

Other layouts

Layouts are also helpful in nested routes. For example, you can add a layout at ./pages/blog/_layout.tsx to add a sidebar to both the blog index and all blog article pages.

// ./src/pages/blog/_layout.tsx
import { Sidebar } from '../../components/sidebar';
// Create blog layout
export default async function BlogLayout({ children }) {
  return (
    <div className="flex">
      <div>{children}</div>
      <Sidebar />
    </div>
  );
}
export const getConfig = async () => {
  return {
    render: 'static',
  } as const;
};

Root element

The attributes of <html>, <head>, or <body> elements can be customized with the root element API. Create a special _root.tsx file in the ./src/pages directory that accepts a children prop of type ReactNode.

// ./src/pages/_root.tsx
// Create root element
export default async function RootElement({ children }) {
  return (
    <html lang="en">
      <head></head>
      <body data-version="1.0">{children}</body>
    </html>
  );
}
export const getConfig = async () => {
  return {
    render: 'static',
  } as const;
};

Slices

Slices are reusable components that are defined in the src/pages/_slices directory. They allow you to compose pages by assembling components like normal React components while specifying alternate rendering patterns.

Creating slices

Slices are created by placing files in the src/pages/_slices directory. The slice ID corresponds to the filename, and nested slices use the full path as the ID.

 src/pages
 ├── _slices
 │   ├── one.tsx
 │   ├── two.tsx
 │   └── nested
 │       └── three.tsx
 └── some-page.tsx

Each slice file exports a default React component and a getConfig function that specifies the render method.

// ./src/pages/_slices/one.tsx
// Create slice component
export default function SliceOne() {
  return <p>🍕</p>;
}
export const getConfig = () => {
  return {
    render: 'static', // default is 'static'
  };
};

// ./src/pages/_slices/nested/three.tsx
// Create nested slice component
export default function SliceThree() {
  return <p>🍰</p>;
}
export const getConfig = () => {
  return {
    render: 'dynamic',
  };
};

Using slices

Slices are used in pages and layouts by importing the Slice component from Waku and specifying the slice ID. The slices array in the page's getConfig must include all slice IDs used on that page.

// ./src/pages/some-page.tsx
import { Slice } from 'waku';
// Create page with slices
export default function SomePage() {
  return (
    <div>
      <Slice id="one" />
      <Slice id="two" />
      <Slice id="nested/three" />
    </div>
  );
}
export const getConfig = () => {
  return {
    render: 'static',
    slices: ['one', 'two', 'nested/three'],
  };
};

Lazy slices

Lazy slices allow components to be requested independently from the page they are used on, similar to Astro's server islands feature. This is useful for components that will be dynamically rendered on otherwise static pages.

Lazy slices are marked with the lazy prop and can include a fallback component to display while loading.

// ./src/pages/some-page.tsx
import { Slice } from 'waku';
// Create page with lazy slice
export default function SomePage() {
  return (
    <div>
      <Slice id="one" />
      <Slice id="two" lazy fallback={<p>Two is loading...</p>} />
    </div>
  );
}
export const getConfig = () => {
  return {
    render: 'static',
    slices: ['one'], // Note: 'two' is lazy, so it is not included
  };
};

This allows you to have a dynamic slice component while keeping the rest of the page static.

Navigation

Link

The <Link /> component should be used for internal links. It accepts a to prop for the destination and handles client-side navigation through Waku's router.

to is either a route string, or a structured { to, params, search, hash } target for typed navigation (the same shape router.push accepts; see Typed Routes).

// ./src/pages/index.tsx
import { Link } from 'waku';
export default async function HomePage() {
  return (
    <>
      <h1>Home</h1>
      <Link to="/about">About</Link>
      <Link to={{ to: '/search', search: { q: 'waku' } }}>Search</Link>
    </>
  );
}

useRouter

The useRouter hook can be used to inspect the current route or perform programmatic navigation.

router properties

The router object has two properties related to the current route: path (string) and query (string).

'use client';
import { useRouter } from 'waku';
export const Component = () => {
  const { path, query } = useRouter();
  return (
    <>
      <div>current path: {path}</div>
      <div>current query: {query}</div>
    </>
  );
};

router methods

The router object also contains several methods for programmatic navigation:

• router.push(to) - navigate to the provided route. to is a route string, or a structured { to, params, search, hash } target for typed navigation to dynamic routes (see Typed Routes)

• router.prefetch(to: string) - prefetch the provided route

• router.replace(to) - replace the current history entry (same argument as push)

• router.reload() - reload the current route

• router.back() - navigate to the previous entry in the session history

• router.forward() - navigate to the next entry in the session history

'use client';
import { useRouter } from 'waku';
export const Component = () => {
  const router = useRouter();
  return (
    <>
      <button onClick={() => router.push('/')}>Home</button>
      <button onClick={() => router.back()}>Back</button>
    </>
  );
};

Error handling

Waku sets up a default error boundary at the root of your application. You can customize error handling by adding your own error boundaries anywhere, for example with the react-error-boundary library.

When errors are thrown from server components or server functions, the errors are automatically replayed on browser. This allows the closest error boundaries to catch and handle these errors, even though they originated on the server.

// ./src/pages/index.tsx
import { ErrorBoundary } from 'react-error-boundary';
export default async function HomePage() {
  return (
    <>
      <ErrorBoundary fallback={<div>Caught server component error!</div>}>
        <ThrowComponent />
      </ErrorBoundary>
      <ErrorBoundary fallback={<div>Caught server function error!</div>}>
        <form
          action={async () => {
            'use server';
            throw new Error('Oops!');
          }}
        >
          <button>Crash</button>
        </form>
      </ErrorBoundary>
    </>
  );
}
const ThrowComponent = async () => {
  throw new Error('Oops!');
  return <>...</>;
};

Error boundaries handle unexpected errors as a last resort safety net. For expected error conditions (like validation or network failures), handle them explicitly in your application logic.

In production, server errors are automatically obfuscated on the client to avoid revealing server internals. Detailed error messages and stack traces are only visible in development.

If you customize the root element (see Root element), you should add your own error boundary there, as Waku's default root error boundary is included in the default root element.

Metadata

Waku automatically hoists any title, meta, and link tags to the document head. That means adding meta tags is as simple as adding them to any of your layout or page components.

// ./src/pages/_layout.tsx
export default async function RootLayout({ children }) {
  return (
    <>
      <link rel="icon" type="image/png" href="/images/favicon.png" />
      <meta property="og:image" content="/images/opengraph.png" />
      {children}
    </>
  );
}
export const getConfig = async () => {
  return {
    render: 'static',
  } as const;
};

// ./src/pages/index.tsx
export default async function HomePage() {
  return (
    <>
      <title>Waku</title>
      <meta name="description" content="The minimal React framework" />
      <h1>Waku</h1>
      <div>Hello world!</div>
    </>
  );
}
export const getConfig = async () => {
  return {
    render: 'static',
  } as const;
};

Metadata can also be generated programmatically.