How Waku’s Development Server Delivers Instant Hot‑Reload for Frontend Assets

The problem: waiting for rebuilds kills iteration speed

When you’re tweaking a component, adjusting a style sheet, or adding a new image, the usual workflow involves stopping the dev server, running a build command, and then refreshing the page. Even a few seconds of delay add up over hundreds of edits, breaking focus and slowing down feature work.

Waku’s solution: a dev server that watches, rebuilds, and serves fresh assets

Waku bundles a development server that automatically monitors the project’s source tree. When a file changes, the server performs an incremental rebuild of only the affected module and pushes the updated asset to the browser with a cache‑busting query string. This means the page updates instantly, without you typing npm run dev again or hitting the refresh button.

What gets watched and rebuilt

• JavaScript/TypeScript files (including page components and API routes)
• CSS, SCSS, and PostCSS stylesheets
• Static assets such as images, SVGs, and fonts
• Configuration files like waku.config.ts (changes trigger a full server restart)

Because the server uses esbuild under the hood, the rebuild step is typically sub‑second for small to medium edits.

How cache‑busting works

Each rebuilt asset receives a unique hash in its URL, for example:

/assets/styles.abc123.css

The browser treats this as a new resource, bypassing any stale cached copy. You can verify this in the DevTools Network tab: look for the Cache-Control header set to no-cache or a short max-age value, and note the changing filename on each save.

Worked example: editing a component and seeing the change

1. Start the dev server from the project root:

npx waku dev

2. Open http://localhost:3000 in your browser. Suppose you see a heading rendered by src/components/Heading.tsx.
3. Edit the file, changing the text from Hello, Waku! to Hello, World! and save.
4. In the terminal you’ll see a log line similar to:

[waku] Rebuilt src/components/Heading.tsx in 120ms

5. Switch back to the browser; the heading updates instantly. No manual refresh is required.
6. Open the Network tab, filter by stylesheet or script, and notice the asset URLs now contain a new hash.

Trade‑offs and limitations

While the dev server is optimized for speed, there are scenarios where the experience degrades:

• Large monorepos: If the project contains thousands of files, the file‑watcher may take longer to detect changes, and the incremental rebuild can stretch to a few seconds.
• Third‑party libraries that mutate files in place: Some packages write directly to node_modules without emitting new files; the watcher may miss these changes, requiring a manual restart.
• Production‑only features: Code that relies on environment variables set only in production (e.g., process.env.NODE_ENV === 'production') will behave differently in dev, so you should still test a production build before release.

To check whether hot‑reload is working as expected, run the dev server, make a change, and then:

1. Confirm the terminal logs a rebuild time.
2. Verify the browser updates without a manual reload.
3. Check the Network tab for cache‑busting URLs.

Actionable closing

If you’re starting a new Waku project or looking to improve your local workflow, rely on the built‑in dev server for instant feedback. Keep an eye on rebuild times in the terminal; if they start to creep upward, consider splitting large modules or disabling watchers for unrelated packages. For production confidence, always run npx waku build and inspect the output before deploying.