Waku's Migration to @vitejs/plugin-rsc

Technical details and breaking changes in Waku's migration to the official Vite React Server Components plugin.

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 support has changed. Vite configuration must now be nested under a vite property in waku.config.ts:

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: {
    environments: {
      // environment-specific configurations.
      // `client`, `ssr`, and `rsc` environments are available.
      client: {
        build: {
          // enable source maps for client build
          sourcemap: true,
        },
      },
      ssr: {
        optimizeeDeps: {
          include: [
            // handle cjs package during SSR
          ],
        },
      },
      rsc: {
        // ...
      },
    },
    plugins: [
      // custom plugins
      {
        name: 'my-custom-plugin',
        transform(code, id) {
          // e.g. transform only on `rsc` environment
          if (this.environment.name === 'rsc') {
            // ...
          }
        },
      },
    ],
  },
});

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.

star Waku on GitHub!