Waku

https://waku.gg
Admin
Waku is a minimal React framework that supports server components and actions, designed for...
Tokens:67,296
Snippets:759
Trust Score:8
Update:3 months ago
Show doc for...
Tokens:
Raw
### Navigate and Run Waku Project

Source: https://waku.gg/guides/getting-started

After scaffolding, navigate into the project directory, install dependencies, and start the development server.

```bash
cd waku-project
npm install
npm run dev
```

--------------------------------

### Example: Custom Vite Configuration with Environments and Plugins

Source: https://waku.gg/blog/migration-to-vite-plugin-rsc

Provides an example of a detailed waku.config.ts setup, showcasing environment-specific Vite configurations and custom plugin integration.

```typescript
import { defineConfig } from 'waku/config';

export default defineConfig({
  vite: {
    environments: {
      // environment-specific configurations.
      client: {
        build: {
          // disable client assets minification
          minify: false,
        },
      },
      ssr: {
        optimizeeDeps: {
          include: [
            // handle cjs package for SSR
          ],
        },
      },
      rsc: {
        // ...
      },
    },
    plugins: [
      // custom plugins
      {
        name: 'my-custom-plugin',
        transform(code, id) {
          // e.g. transform only on `rsc` environment
          if (this.environment.name === 'rsc') {
            // ...
          }
        },
      },
    ],
  },
});

```

--------------------------------

### Programmatic Routing Setup

Source: https://waku.gg/

Configures programmatic routing by calling `createPages` in `waku.server.tsx`. This example demonstrates creating root components, layouts, pages, slices, and API endpoints with specified render methods.

```typescript
// ./src/waku.server.tsx
import { createPages } from 'waku';
import adapter from 'waku/adapters/default';

import { RootLayout } from './templates/root-layout';
import { HomePage } from './templates/home-page';
import { Root } from './components/root';
import { Slice } from './components/slice';

const pages = createPages(
  async ({ createPage, createLayout, createRoot, createSlice, createApi }) => [
    // Create root component
    // not required, but supported for customizing
    // `<html>`, `<head>`, and `<body>` tags
    createRoot({
      render: 'static',
      component: Root,
    }),

    // Create root layout
    createLayout({
      render: 'static',
      path: '/',
      component: RootLayout,
    }),

    // Create home page
    createPage({
      render: 'dynamic',
      path: '/',
      component: HomePage,
    }),

    // Create slice
    createSlice({
      render: 'static',
      component: Slice,
      id: 'slice-1',
    }),

    // Create API endpoint
    createApi({
      render: 'static',
      path: '/health',
      method: 'GET',
      handler: async () => new Response('OK'),
    }),
  ],
);

export default adapter(pages);
```

--------------------------------

### Global Stylesheet Example

Source: https://waku.gg/llms.txt

Example of a global stylesheet using Tailwind CSS. This file should be imported into the root layout.

```css
/* ./src/styles.css */
@import 'tailwindcss';

```

--------------------------------

### Build and Start Docker Container

Source: https://waku.gg/guides/docker

Command to build the Docker image and start the Waku application container using Docker Compose. The application will be accessible at http://localhost:8080.

```bash
docker compose up --build
```

--------------------------------

### Async Server Component Example

Source: https://waku.gg/guides/getting-started

This is an example of an async server component in Waku. Server components execute on the server, allowing secure access to data and reducing client bundle size. They render only once.

```typescript
export default async function HomePage() {
  const data = await getData();
  // ...rest of the file
}
```

--------------------------------

### Waku Slice Component Example

Source: https://waku.gg/blog/rethinking-fine-grained-components

A basic example of a Waku slice component. The `getConfig` function can specify the render mode, defaulting to 'static'.

```tsx
export default function SliceOne() {
  return <p>🍕</p>;
}

export const getConfig = () => {
  return {
    render: 'static', // default is 'static'
  };
};
```

--------------------------------

### Create Static API Route in Waku

Source: https://waku.gg/

Example of creating a static API route in Waku that supports GET requests. This API will be emitted at build time.

```tsx
// ./src/waku.server.tsx
import { createPages } from 'waku';
import adapter from 'waku/adapters/default';

const pages = createPages(async ({ createApi }) => [
  createApi({
    render: 'static',
    path: '/rss.xml',
    method: 'GET',
    handler: async () => {
      return new Response('<rss />', {
        headers: { 'Content-Type': 'application/rss+xml' },
      });
    },
  }),
]);

export default adapter(pages);

```

--------------------------------

### Install Dependencies for React Compiler

Source: https://waku.gg/guides/react-compiler

Use this command to install the necessary Vite React plugin, React Compiler Babel plugin, and the Rolldown Babel plugin for older Waku projects that do not have React Compiler configured.

```bash
npm install -D @vitejs/plugin-react babel-plugin-react-compiler @rolldown/plugin-babel
```

--------------------------------

### Client Component Example

Source: https://waku.gg/llms.txt

Example of a client component marked with 'use client'. It can utilize React features like state and event handlers, and will be hydrated to run in the browser.

```tsx
// 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>
    </>
  );
};
```

--------------------------------

### Minimal Client Runtime Setup

Source: https://waku.gg/guides/minimal-api

Set up the minimal Waku client runtime using `Root` and `Slot` for hydration or initial rendering. This code is typically placed in `src/waku.client.tsx`.

```typescript
import { StrictMode } from 'react';
import { createRoot, hydrateRoot } from 'react-dom/client';
import { Root, Slot } from 'waku/minimal/client';

const rootElement = (
  <StrictMode>
    <Root>
      <Slot id="App" />
    </Root>
  </StrictMode>
);

if ((globalThis as any).__WAKU_HYDRATE__) {
  hydrateRoot(document, rootElement);
} else {
  createRoot(document).render(rootElement);
}
```

--------------------------------

### Static API Example

Source: https://waku.gg/

Defines a static API endpoint for RSS feed generation that can be emitted at build time.

```APIDOC
## GET /rss.xml

### Description
Provides a static RSS feed.

### Method
GET

### Endpoint
/rss.xml

### Request Example
(No request body for GET request)

### Response
#### Success Response (200)
- **Content-Type**: application/rss+xml
- **Body**: XML content of the RSS feed.

### Response Example
```xml
<rss />
```
```

--------------------------------

### Create Dynamic API Route in Waku

Source: https://waku.gg/

Example of creating a dynamic API route in Waku. This route supports GET requests with parameters and has a fallback for unhandled methods.

```tsx
const pages = createPages(async ({ createApi }) => [
  createApi({
    render: 'dynamic',
    path: '/api/users/[id]',
    handlers: {
      GET: async (_req, { params }) => {
        return Response.json({ id: params.id });
      },
      all: async () => new Response('Method not allowed', { status: 405 }),
    },
  }),
]);

```

--------------------------------

### Deploy to Vercel CLI

Source: https://waku.gg/llms.txt

Use the Vercel CLI to automatically deploy Waku projects. Ensure you have the Vercel CLI installed and are logged in.

```sh
vercel
```

--------------------------------

### Server Component Example

Source: https://waku.gg/llms.txt

Example of a server component that can perform server-side logic and data fetching. It securely accesses a database and imports heavy dependencies without affecting the client bundle.

```tsx
// 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} />; 
};
```

--------------------------------

### Install Cloudflare Vite Plugin and Wrangler

Source: https://waku.gg/guides/cloudflare

Install the necessary development dependencies for Cloudflare Workers integration.

```bash
npm install --save-dev @cloudflare/vite-plugin wrangler
```

--------------------------------

### Root Layout with Server and Client Components

Source: https://waku.gg/

This example demonstrates how a server component (RootLayout) can import and wrap a client component (Providers), establishing a server-client boundary. Server components can accept server components as props like children.

```typescript
// ./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;
};

```

```typescript
// ./src/components/providers.tsx
'use client';

import { Provider } from 'jotai';

export const Providers = ({ children }) => {
  return <Provider>{children}</Provider>;
};

```

--------------------------------

### Dynamic Route for Instant Navigation

Source: https://waku.gg/guides/navigation-prefetching

This is an example of a dynamic route that can be streamed into a Suspense fallback during instant navigation. Ensure the route is configured for dynamic rendering.

```javascript
import type { PageProps } from 'waku/router';

export default async function Post({ id }: PageProps<'/posts/[id]'>) {
  const post = await loadPost(id); // request-specific work
  return <article>{post.body}</article>;
}

export const getConfig = async () => {
  return { render: 'dynamic' } as const;
};
```

--------------------------------

### Server actions with progressive enhancement

Source: https://waku.gg/guides/minimal-api

Example of server actions returning HTML for progressive enhancement, working with or without JavaScript.

```typescript
if (
  (input.type === 'action' || input.type === 'custom') &&
  input.pathname === '/'
) {
  const formState = input.type === 'action' ? await input.fn() : undefined;
  return renderHtml(
    await renderRsc({ App: <App name="Waku" /> }),
    <Slot id="App" />,
    {
      rscPath: '',
      formState,
    },
  );
}

```

--------------------------------

### Default Waku Project Setup with React Compiler

Source: https://waku.gg/guides/react-compiler

This configuration is included by default in new Waku projects created with `npm create waku@latest`. It sets up Vite with Tailwind CSS, the Vite React plugin, and the Babel plugin for React Compiler.

```typescript
import babel from '@rolldown/plugin-babel';
import tailwindcss from '@tailwindcss/vite';
import react, { reactCompilerPreset } from '@vitejs/plugin-react';
import { defineConfig } from 'waku/config';

export default defineConfig({
  vite: {
    plugins: [
      tailwindcss(),
      react(),
      babel({ presets: [reactCompilerPreset()] }),
    ],
  },
});
```

--------------------------------

### Layout with Server-Client Boundary

Source: https://waku.gg/llms.txt

Example of a root layout that uses a server component to wrap children, potentially including global context providers. It demonstrates how server components can import client components to establish a server-client boundary.

```tsx
// ./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;
};
```

```tsx
// ./src/components/providers.tsx
'use client';

import { Provider } from 'jotai';

export const Providers = ({ children }) => {
  return <Provider>{children}</Provider>;
};
```

--------------------------------

### Waku Client Router Setup

Source: https://waku.gg/guides/custom-router

Sets up the Waku router client for a React application. Ensure this is used in your client entry point.

```tsx
// src/waku.client.tsx
import { StrictMode } from 'react';
import { createRoot, hydrateRoot } from 'react-dom/client';
import { unstable_defaultRootOptions as defaultRootOptions } from 'waku/client';
import { ErrorBoundary, Router } from 'waku/router/client';

const rootElement = (
  <StrictMode>
    <ErrorBoundary>
      <Router />
    </ErrorBoundary>
  </StrictMode>
);

if ((globalThis as any).__WAKU_HYDRATE__) {
  hydrateRoot(document, rootElement, defaultRootOptions);
} else {
  createRoot(document, defaultRootOptions).render(rootElement);
}
```

--------------------------------

### Create Root Layout with Static Rendering

Source: https://waku.gg/blog/introducing-pages-router

Define a root layout component that wraps the entire application. This example uses static rendering for the header and footer.

```tsx
// ./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',
  };
};

```

--------------------------------

### Server-Side Data Fetching with React Server Components

Source: https://waku.gg/

Example of fetching blog article data on the server using React Server Components. This pattern compiles MDX and performs syntax highlighting on the server, minimizing client bundle size. It requires `getArticle` and `getStaticPaths` functions from a local library.

```tsx
// ./src/pages/blog/[slug].tsx
import type { PageProps } from 'waku/router';

import { MDX } from '../../components/mdx';
import { getArticle, getStaticPaths } from '../../lib/blog';

export default async function BlogArticlePage({
  slug,
}: PageProps<'/blog/[slug]'>) {
  const article = await getArticle(slug);

  return (
    <>
      <title>{article.frontmatter.title}</title>
      <h1>{article.frontmatter.title}</h1>
      <MDX>{article.content}</MDX>
    </>
  );
}

export const getConfig = async () => {
  const staticPaths = await getStaticPaths();

  return {
    render: 'static',
    staticPaths,
  } as const;
};

```

--------------------------------

### Dockerfile for Waku App

Source: https://waku.gg/guides/docker

This Dockerfile uses a multi-stage build to create a lean production image. It installs dependencies, builds the application, and copies only the necessary artifacts to the final image.

```dockerfile
FROM node:22-alpine AS builder

WORKDIR /app

COPY package*.json ./
RUN npm ci

COPY . .
RUN npm run build

FROM node:22-alpine AS runner

WORKDIR /app
ENV NODE_ENV=production

COPY package*.json ./
RUN npm ci --omit=dev

COPY --from=builder /app/dist ./dist

EXPOSE 8080

CMD ["npm", "run", "start"]
```

--------------------------------

### Attach Search Codec with createPages

Source: https://waku.gg/guides/typed-routes

This example shows how to attach a search codec to a specific route using Waku's `createPages` function. It involves declaring the codec in the router's type definitions and passing the codec instance to the `unstable_searchCodec` option when creating the page.

```typescript
import { searchCodec } from './lib/search';

declare module 'waku/router' {
  interface SearchCodecsConfig {
    '/products': typeof searchCodec;
  }
}

// inside createPages(...)
createPage({
  render: 'dynamic',
  path: '/products',
  component: ProductsPage,
  unstable_searchCodec: searchCodec,
});
```

--------------------------------

### Server-Side Data Fetching with MDX

Source: https://waku.gg/llms.txt

Example of fetching blog article data on the server using React Server Components and rendering it with MDX. This pattern is useful for pre-rendering content and reducing client bundle size.

```tsx
// ./src/pages/blog/[slug].tsx
import type { PageProps } from 'waku/router';

import { MDX } from '../../components/mdx';
import { getArticle, getStaticPaths } from '../../lib/blog';

export default async function BlogArticlePage({
  slug,
}: PageProps<'/blog/[slug]'>) {
  const article = await getArticle(slug);

  return (
    <>
      <title>{article.frontmatter.title}</title>
      <h1>{article.frontmatter.title}</h1>
      <MDX>{article.content}</MDX>
    </>
  );
}

export const getConfig = async () => {
  const staticPaths = await getStaticPaths();

  return {
    render: 'static',
    staticPaths,
  } as const;
};
```

--------------------------------

### Create Static API with Dynamic Segments in Waku

Source: https://waku.gg/

Example of creating a static API route with dynamic segments in Waku. It uses `staticPaths` to define possible values for the dynamic segment.

```tsx
createApi({
  render: 'static',
  path: '/feeds/[category]',
  method: 'GET',
  staticPaths: ['news', 'docs'],
  handler: async (_req, { params }) => {
    return new Response(`Feed for ${params.category}`);
  },
});

```

--------------------------------

### Create Server Entry Adapter with Environment Bindings

Source: https://waku.gg/guides/adapter-authoring

Demonstrates creating a server entry adapter that processes requests and builds, while also setting platform environment bindings using setAllEnv. This is useful for platforms like Cloudflare Workers.

```javascript
export default createServerEntryAdapter(
  ({ processRequest, processBuild, setAllEnv }) => {
    return {
      fetch: async (req: Request, env: Record<string, string>) => {
        setAllEnv(env);
        const res = await processRequest(req);
        return res || new Response('Not Found', { status: 404 });
      },
      build: processBuild,
    };
  },
);
```

--------------------------------

### Import Preview Server Builder

Source: https://waku.gg/guides/adapter-authoring

Import `unstable_startPreviewServer` for platforms that need to execute Waku through a local runtime during the build process.

```typescript
import { unstable_startPreviewServer as startPreviewServer } from 'waku/adapter-builders';
```

--------------------------------

### Using Minimal Adapter in Waku Server

Source: https://waku.gg/guides/adapter-authoring

Shows how to integrate the custom minimal adapter with Waku's file system router in the server entry point.

```typescript
import { fsRouter } from 'waku';
import adapter from './my-waku-adapter';

export default adapter(
  fsRouter(import.meta.glob('./**/*.{tsx,ts}', { base: './pages' })),
);
```

--------------------------------

### GET /blog/rss.xml (Static)

Source: https://waku.gg/

Handles GET requests for the /blog/rss.xml endpoint and is configured for static rendering.

```APIDOC
## GET /blog/rss.xml

### Description
Handles GET requests for the /blog/rss.xml endpoint and is configured for static rendering.

### Method
GET

### Endpoint
/blog/rss.xml

### Response
#### Success Response (200)
- Content of the RSS feed (application/rss+xml)

### Response Example
(Content of the RSS feed)

```

--------------------------------

### Bun Build Command

Source: https://waku.gg/llms.txt

Build the Waku project for deployment with Bun.

```sh
npm run build
```

--------------------------------

### GET /users/[id]

Source: https://waku.gg/llms.txt

Handles GET requests to dynamic user endpoints. It extracts the 'id' from the route parameters and returns a personalized message.

```APIDOC
## GET /users/[id]

### Description
Handles GET requests to dynamic user endpoints. It extracts the 'id' from the route parameters and returns a personalized message.

### Method
GET

### Endpoint
/users/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the user.

### Response
#### Success Response (200)
- **id** (string) - The ID of the user.
- **message** (string) - A message including the user ID, e.g., "Hello user 123".
```

--------------------------------

### Minimal Waku Server Entry Adapter

Source: https://waku.gg/guides/adapter-authoring

This snippet demonstrates the simplest Waku adapter for handling runtime requests and build processes. It's useful for understanding the core adapter contract.

```typescript
// my-waku-adapter.ts
import { unstable_createServerEntryAdapter as createServerEntryAdapter } from 'waku/adapter-builders';

export default createServerEntryAdapter(({ processRequest, processBuild }) => {
  return {
    fetch: async (req: Request) => {
      const res = await processRequest(req);
      return res || new Response('Not Found', { status: 404 });
    },
    build: processBuild,
  };
});
```

--------------------------------

### GET /blog/rss.xml (Static)

Source: https://waku.gg/llms.txt

Handles GET requests for an RSS feed, configured to be statically generated. Exports a `getConfig` function to specify static rendering.

```APIDOC
## GET /blog/rss.xml

### Description
Handles GET requests for an RSS feed, configured to be statically generated. Exports a `getConfig` function to specify static rendering.

### Method
GET

### Endpoint
/blog/rss.xml

### Response
#### Success Response (200)
- **Content-Type**: `application/rss+xml` - The response will be an XML document representing the RSS feed.

### Configuration
#### `getConfig` function
Exports a `getConfig` function that returns `{ render: 'static' }` to enable static generation.
```

--------------------------------

### Scaffold a New Waku Project

Source: https://waku.gg/guides/getting-started

Use this command to create a new Waku project. Follow the CLI prompts for configuration. Default project name is 'waku-project'.

```bash
npm create waku@latest
```

--------------------------------

### GET /files/[...path]

Source: https://waku.gg/llms.txt

Handles GET requests to wildcard routes for file paths. It captures all path segments and returns them in a JSON response.

```APIDOC
## GET /files/[...path]

### Description
Handles GET requests to wildcard routes for file paths. It captures all path segments and returns them in a JSON response.

### Method
GET

### Endpoint
/files/*

### Parameters
#### Path Parameters
- **path** (string[]) - Required - An array of strings representing the path segments.

### Response
#### Success Response (200)
- **segments** (string[]) - An array of strings representing the captured path segments.
```

--------------------------------

### Create New Waku Project with Cloudflare Template

Source: https://waku.gg/blog/cloudflare-workers-out-of-the-box

Use the `npm create waku@latest` command with the `-- --template 07_cloudflare` flag to bootstrap a new Waku project pre-configured for Cloudflare Workers, including the necessary loader and Vite plugin.

```bash
npm create waku@latest -- --template 07_cloudflare
```

--------------------------------

### Deno Deploy Command

Source: https://waku.gg/llms.txt

Build the Waku project and deploy it to Deno Deploy using `deployctl`. Exclude `node_modules` during deployment.

```sh
npm run build
deployctl deploy --prod dist/serve-deno.js --exclude node_modules
```

--------------------------------

### Create Blog Article Page with Static Paths

Source: https://waku.gg/blog/introducing-pages-router

A dynamic route for individual blog articles, configured for static rendering. It requires a `staticPaths` array to define all possible routes at build time.

```tsx
// ./src/pages/blog/[slug].tsx

// Create blog article pages
export default async function BlogArticlePage({ slug }) {
  const data = await getData(slug);

  return <>{/* ...*/}</>;
}

const getData = async (slug) => {
  /* ... */
};

export const getConfig = async () => {
  return {
    render: 'static',
    staticPaths: ['introducing-waku', 'introducing-pages-router'],
  };
};

```

--------------------------------

### Pure SSG Deployment on Netlify

Source: https://waku.gg/llms.txt

Configure Waku for pure static site generation on Netlify by using the Netlify adapter with the `static: true` option. This avoids deploying functions.

```typescript
import { fsRouter } from 'waku';
import adapter from 'waku/adapters/netlify';

export default adapter(fsRouter(import.meta.glob('./pages/**/*.{tsx,ts}')), {
  static: true,
});
```

--------------------------------

### Dynamic API Example

Source: https://waku.gg/

Defines a dynamic API endpoint that accepts a user ID and returns it in the response.

```APIDOC
## Dynamic API with GET and fallback handler

### Description
Handles dynamic API requests, specifically for retrieving user information by ID, with a fallback for unsupported methods.

### Method
GET, ALL (fallback)

### Endpoint
/api/users/[id]

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the user.

### Request Example
(No request body for GET request)

### Response
#### Success Response (200)
- **id** (string) - The ID of the user.

#### Error Response (405)
- **Body**: 'Method not allowed'

### Response Example
```json
{
  "id": "some-user-id"
}
```
```

--------------------------------

### Configure Pages and Slices in Waku Server

Source: https://waku.gg/

Sets up the Waku server configuration, defining a static page ('/') that uses two slices ('one' and 'two'), and also defines the slices themselves.

```tsx
// ./src/waku.server.tsx
import { createPages } from 'waku';
import adapter from 'waku/adapters/default';

import { HomePage } from './templates/home-page';
import { SliceOne } from './components/slice-one';
import { SliceTwo } from './components/slice-two';

const pages = createPages(async ({ createPage, createSlice }) => [
  createPage({
    render: 'static',
    path: '/',
    component: HomePage,
    slices: ['one', 'two'],
  }),

  createSlice({
    render: 'static',
    component: SliceOne,
    id: 'one',
  }),

  createSlice({
    render: 'dynamic',
    component: SliceTwo,
    id: 'two',
  }),
]);

export default adapter(pages);

```

--------------------------------

### Custom API endpoint

Source: https://waku.gg/guides/minimal-api

Example of defining a custom API endpoint using input.type === 'custom' and returning a Response.

```typescript
if (input.type === 'custom' && input.pathname === '/api/hello') {
  return new Response('world');
}

```

--------------------------------

### Deploy to Netlify CLI

Source: https://waku.gg/llms.txt

Deploy Waku projects to Netlify using the Netlify CLI. Set the NETLIFY environment variable and run the build command before deploying.

```sh
NETLIFY=1 npm run build
netlify deploy
```

--------------------------------

### Static Layout Component

Source: https://waku.gg/llms.txt

A static layout component that applies a 'main-container' class to its children. This is an example of a static layout at the group level.

```tsx
// ./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;
};
```

--------------------------------

### Server functions with value option

Source: https://waku.gg/guides/minimal-api

Example of a server function returning its result with the value option and optionally updated server elements.

```typescript
if (input.type === 'function') {
  const value = await input.fn(...input.args);
  return renderRsc({ App: <App name="Updated" /> }, { value });
}

```

--------------------------------

### Dynamic SSR without prerendering

Source: https://waku.gg/guides/minimal-api

Example of handling requests for dynamic SSR without prerendering using renderHtml and an empty handleBuild.

```typescript
export default adapter({
  handleRequest: async (input, { renderRsc, renderHtml }) => {
    if (input.type === 'component') {
      return renderRsc({ App: <App name={input.rscPath || 'Waku'} /> });
    }
    if (input.type === 'custom' && input.pathname === '/') {
      return renderHtml(
        await renderRsc({ App: <App name="Waku" /> }),
        <Slot id="App" />,
        { rscPath: '' },
      );
    }
    return null;
  },
  handleBuild: async () => {},
});

```

--------------------------------

### Bun Configuration

Source: https://waku.gg/llms.txt

Configure Waku for deployment with Bun using the Bun adapter. This is an experimental feature.

```typescript
import { fsRouter } from 'waku';
import adapter from 'waku/adapters/bun';

export default adapter(fsRouter(import.meta.glob('./pages/**/*.{tsx,ts}')));
```

--------------------------------

### Use useRefetch for dynamic data fetching

Source: https://waku.gg/guides/minimal-api

Example of using the useRefetch hook to fetch new RSC payloads and update the UI.

```typescript
import { useTransition } from 'react';
import { useRefetch } from 'waku/minimal/client';

const Counter = () => {
  const [isPending, startTransition] = useTransition();
  const refetch = useRefetch();

  const handleClick = (count: number) => {
    startTransition(async () => {
      await refetch('InnerApp=' + count);
    });
  };

  return (
    <button onClick={() => handleClick(1)} disabled={isPending}>
      Refetch
    </button>
  );
};

```

--------------------------------

### Create Blog Index Page with Static Rendering

Source: https://waku.gg/blog/introducing-pages-router

A component for the blog's index page, configured for static rendering. This page would typically list blog post summaries.

```tsx
// ./src/pages/blog.tsx

// Create blog index page
export default async function BlogIndexPage() {
  return <>{/* ...*/}</>;
}

export const getConfig = async () => {
  return {
    render: 'static',
  };
};

```

--------------------------------

### Redirects Configuration for Vercel

Source: https://waku.gg/guides/redirect-maps

Define redirects in `vercel.json` for your Vercel deployment. This example shows how to redirect both a user-facing path and its associated RSC payload path.

```json
{
  "redirects": [
    { "source": "/old", "destination": "/new", "permanent": true },
    {
      "source": "/RSC/R/old.txt",
      "destination": "/RSC/R/new.txt",
      "permanent": true
    }
  ]
}
```

--------------------------------

### Manual Nonce Passing in waku.server.tsx

Source: https://waku.gg/guides/csp

This example shows how to manually generate a nonce and pass it to `renderHtml` and the Content-Security-Policy header when customizing the `handleRequest` function in `waku.server.tsx`.

```typescript
import adapter from 'waku/adapters/default';
import { Slot } from 'waku/minimal/client';
import App from './components/App.js';
import { encodeBase64 } from 'hono/utils/encode';

const generateNonce = () => {
  const arrayBuffer = new Uint8Array(16);
  crypto.getRandomValues(arrayBuffer);
  return 'toBase64' in arrayBuffer
    ? arrayBuffer.toBase64()
    : encodeBase64(arrayBuffer.buffer);
};

export default adapter({
  handleRequest: async (input, { renderRsc, renderHtml }) => {
    if (input.type === 'component') {
      return renderRsc({ App: <App /> });
    }
    if (input.type === 'custom' && input.pathname === '/') {
      const nonce = generateNonce();
      const response = await renderHtml(
        await renderRsc({ App: <App /> }),
        <Slot id="App" />,
        {
          rscPath: '',
          nonce,
        },
      );

      response.headers.set(
        'Content-Security-Policy',
        `script-src 'self' 'nonce-${nonce}';`,
      );

      return response;
    }
    return null;
  },
  handleBuild: async () => {},
});

```

--------------------------------

### Client Component Example

Source: https://waku.gg/guides/getting-started

This component is marked as a client component with the 'use client' directive. It utilizes familiar React client-side APIs like useState.

```typescript
'use client';

import { useState } from 'react';

export const Counter = () => {
  const [count, setCount] = useState(0);
  // ...rest of the file
};
```

--------------------------------

### Static Host Configuration

Source: https://waku.gg/guides/static-deployments

Configure your static host to use `dist/public` as the publish directory. Ensure generated files, including RSC payloads, are served correctly.

```text
dist/public
```

--------------------------------

### Before: Waku Configuration

Source: https://waku.gg/blog/migration-to-vite-plugin-rsc

Shows the previous approach to configuring Vite settings within waku.config.ts using unstable_viteConfigs.

```typescript
import { defineConfig } from "waku/config";

export default defineConfig({
  unstable_viteConfigs: { ... },
})

```

--------------------------------

### Static Waku App Deployment Configuration

Source: https://waku.gg/guides/cloudflare

Configure wrangler.jsonc for a static-only Waku app deployment. This setup bypasses the worker and serves only static assets.

```json
{
  "name": "waku-project",
  "compatibility_date": "2025-11-17",
  "assets": {
    "directory": "./dist/public",
    "html_handling": "drop-trailing-slash"
  }
}
```

--------------------------------

### Create Nested Slice Component

Source: https://waku.gg/

Defines a nested slice component with its configuration. This example shows a slice located in a subdirectory, with its render method set to 'dynamic'.

```typescript
// ./src/pages/_slices/nested/three.tsx

// Create nested slice component
export default function SliceThree() {
  return <p>🍰</p>;
}

export const getConfig = () => {
  return {
    render: 'dynamic',
  };
};
```

--------------------------------

### Handle Build: Generate Fallback HTML Only

Source: https://waku.gg/guides/minimal-api

Generates only the default fallback HTML file, suitable for Single Page Application (SPA) builds.

```javascript
handleBuild: async ({ generateDefaultHtml }) => {
  await generateDefaultHtml('index.html');
},

```

--------------------------------

### Shared Component Example

Source: https://waku.gg/llms.txt

A simple React component that adheres to the rules for both server and client components, allowing it to be imported into either without impacting the server-client boundary.

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

--------------------------------

### Create Home Page with Dynamic Rendering

Source: https://waku.gg/blog/introducing-pages-router

Implement a home page component that fetches data and is dynamically rendered at request time. Ensure the necessary data fetching logic is included.

```tsx
// ./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',
  };
};

```

--------------------------------

### Production Build Command

Source: https://waku.gg/guides/static-deployments

Run the standard production build command to generate static files. The output will be placed in the `dist/public` directory.

```bash
pnpm exec waku build
```

--------------------------------

### Set Response Cookies from Middleware

Source: https://waku.gg/guides/request-context

Implement middleware to set response cookies. This example demonstrates parsing existing cookies, processing them, and appending a 'set-cookie' header to the response.

```typescript
// src/middleware/session.ts
import * as cookie from 'cookie';
import type { MiddlewareHandler } from 'hono';

const sessionMiddleware = (): MiddlewareHandler => {
  return async (c, next) => {
    const cookies = cookie.parseCookie(c.req.header('cookie') || '');
    const sessionId = cookies.sessionId;

    await next();

    if (c.res && sessionId) {
      const headers = new Headers(c.res.headers);
      headers.append(
        'set-cookie',
        cookie.stringifySetCookie({
          name: 'sessionId',
          value: sessionId,
          httpOnly: true,
          path: '/',
          sameSite: 'lax',
          secure: true,
        }),
      );
      c.res = new Response(c.res.body, {
        status: c.res.status,
        statusText: c.res.statusText,
        headers,
      });
    }
  };
};

export default sessionMiddleware;
```

--------------------------------

### Import Shared Atom in a Client Component

Source: https://waku.gg/guides/state-across-client-server

Import the shared state definition from a neutral module into a client component. This example shows how to use the `useAtom` hook from Jotai.

```typescript
// src/components/counter.tsx
'use client';

import { useAtom } from 'jotai';
import { countAtom } from '../state/count';

export const Counter = () => {
  const [count, setCount] = useAtom(countAtom);
  return (
    <button onClick={() => setCount((count) => count + 1)}>{count}</button>
  );
};
```

--------------------------------

### Waku Configuration for Tailwind CSS

Source: https://waku.gg/

Configure Waku to use Tailwind CSS by adding it as a Vite plugin in the waku.config.ts file. This setup is necessary for Tailwind to process your styles.

```ts
// ./waku.config.ts
import { defineConfig } from 'waku/config';
import tailwindcss from '@tailwindcss/vite';

export default defineConfig({
  vite: {
    plugins: [tailwindcss()],
  },
});
```

--------------------------------

### Before: Vite Configuration

Source: https://waku.gg/blog/migration-to-vite-plugin-rsc

Illustrates the previous method of configuring Vite in a separate vite.config.ts file.

```typescript
import { defineConfig } from "vite";

export default defineConfig({ ... })

```

--------------------------------

### Conditionally Disable SSR for Specific Paths

Source: https://waku.gg/guides/no-ssr

Implement conditional logic within your custom server's `handleRequest` function to disable SSR only for specific paths, such as those starting with '/app'.

```typescript
handleRequest: async (input, utils) => {
  if (input.type === 'custom' && input.pathname.startsWith('/app')) {
    return 'fallback';
  }
  return router.handleRequest(input, utils);
};
```

--------------------------------

### Client-Side Rendering with Waku Slots

Source: https://waku.gg/blog/introducing-waku

Utilize `Root` and `Slot` from 'waku/client' to render server-provided components. `Root` initializes the RSC process with an `initialInput`, and `Slot` displays the component associated with a specific ID.

```typescript
import { createRoot } from 'react-dom/client';
import { Root, Slot } from 'waku/client';

const rootElement = (
  <Root initialInput="Waku">
    <Slot id="App" />
  </Root>
);

createRoot(document.getElementById('root')).render(rootElement);
```

--------------------------------

### Waku Cloudflare Server Entrypoint

Source: https://waku.gg/guides/cloudflare

Create the server entry point for Waku on Cloudflare Workers using the provided adapter.

```typescript
// ./src/waku.server.tsx
import { fsRouter } from 'waku';
import adapter from 'waku/adapters/cloudflare';

export default adapter(fsRouter(import.meta.glob('./pages/**/*.{tsx,ts}')));

```

--------------------------------

### Dedupe React in Vite Configuration

Source: https://waku.gg/guides/monorepo

Configure Vite to deduplicate React and React DOM installations when bundling linked workspace packages. This ensures a single version is used across the monorepo.

```typescript
import { defineConfig } from 'waku/config';

export default defineConfig({
  vite: {
    resolve: {
      dedupe: ['react', 'react-dom'],
    },
  },
});
```

--------------------------------

### Add Metadata to Layout Component

Source: https://waku.gg/

Hoist title, meta, and link tags to the document head by adding them to your layout component. This example shows adding a favicon and an Open Graph image.

```tsx
// ./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;
};
```

--------------------------------

### After: Waku Configuration

Source: https://waku.gg/blog/migration-to-vite-plugin-rsc

Demonstrates the new method for specifying Vite configuration directly within the 'vite' property in waku.config.ts.

```typescript
import { defineConfig } from "waku/config";

export default defineConfig({
  vite: { ... }
})

```
Tokens:
Raw