Quick Start

Prerequisites

• Node.js ^26.0.0, ^24.0.0, or ^22.15.0
• Any package manager (the commands below use npm)

Scaffold a project

Run the following command in your terminal:

npm create waku@latest

Follow the CLI prompts. The default project name is waku-project. Then install dependencies and start the development server:

cd waku-project
npm install
npm run dev

Open http://localhost:3000 in your browser. You should see a small demo app with an interactive counter.

Project structure

The starter contains the following files:

waku-project/
├── public/            # static assets served as-is
├── src/
│   ├── components/    # reusable React components
│   ├── middleware/    # optional server middleware
│   ├── pages/         # file-based routes
│   │   ├── _layout.tsx
│   │   ├── about.tsx
│   │   └── index.tsx
│   ├── global.d.ts
│   └── styles.css
├── package.json
├── tsconfig.json
└── waku.config.ts

• src/pages is the router: each file becomes a route, and _layout.tsx wraps the pages next to and below it.
• src/components holds regular React components that pages import.
• src/middleware contains optional Hono middleware that the default setup picks up automatically. The starter ships one that removes trailing slashes. In production, statically generated pages are served before middleware runs, so it only applies to dynamic routes; see Redirect Maps.
• public files are copied to the site root unchanged, such as images and fonts.
• waku.config.ts configures Waku and Vite. The starter enables Tailwind CSS and React Compiler plugins.

While the development server is running, Waku also generates src/pages.gen.ts containing route types for type-safe links. It is regenerated automatically whenever your pages change, so you never edit it by hand.

Make your first edit

Open src/pages/index.tsx:

// ./src/pages/index.tsx (excerpt)
export default async function HomePage() {
  const data = await getData();

  return (
    <div>
      <title>{data.title}</title>
      <h1 className="text-4xl font-bold tracking-tight">{data.headline}</h1>
      <p>{data.body}</p>
      <Counter />
      <Link to="/about" className="mt-4 inline-block underline">
        About page
      </Link>
    </div>
  );
}

The content comes from a getData function defined below the component. Change its body text and save. The browser updates instantly without a full reload.

Commands

• npm run dev starts the development server at http://localhost:3000
• npm run build creates a production build in dist
• npm run start serves the production build at http://localhost:8080

Next Step

Read What is Waku? for a tour of what the framework offers.