Waku's Migration to @vitejs/plugin-rsc

Waku has migrated to use Vite's official plugin @vitejs/plugin-rsc for its React Server Components bundler implementation. This unifies/simplifies/unlocks .... (TODO: mention Environment API.)

While there were significant changes in underlying dev server, plugin, and build pipeline architecture, core routing logic remains almost unchanged, preserving Waku's existing functionality. This is thanks to Waku's "layered" routing architecture where the higher level APIs (fsRouter, createPages, defineRouter) are built up through the lowest level "minimal" API defineEntries.

New features / Breaking Changes

Custom Vite configuration has changed. Vite configuration must now be nested under a vite property in waku.config.ts:

TODO: mention client/ssr/rsc environments. add plugin examples. TODO: link to Environment plugin API (e.g. applyToEnvironment, this.environment). https://vite.dev/guide/api-environment-plugins.html

Before

// vite.config.ts
import { defineConfig } from "vite";

export default defineConfig({ ... })

// waku.config.ts
import { defineConfig } from "waku/config";

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

After

// waku.config.ts
import { defineConfig } from "waku/config";

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

Example

// waku.config.ts
import { defineConfig } from "waku/config";

export default defineConfig({
  vite: {
    plugins: [
    ],
    environments: {
      ssr: {},
    }
  }
})

Previous Implementation

The previous implementation remains available via the --experimental-legacy-cli flag for fallback during the transition period, for example,

waku dev --experimental-legacy-cli
waku build --experimental-legacy-cli
waku start --experimental-legacy-cli

This flag allows reverting to the previous behavior while the new implementation is refined based on usage feedback.

Future

• @cloudflare/vite-plugin
• Nitro plugin?
• Better alignment with Vite ecosystem.
• Rolldown-Vite support.