Tips for anyone experiencing Cloudflare build issues after upgrading

[jkhaui]

I learned a few days ago that Waku already migrated to the new Vite RSC plugin. Congrats team!

I was able to go from 0.23.2 -> 0.25.0 with relatively few changes (surprisingly), which is a testament to Waku's design.

But as with any build tool upgrade, of course there had to be a few things break for the last 10-20%. I wanted to share my learnings here. This is mostly about Vite-related config and how it relates to Cloudflare builds, where I know people like to deploy Waku.

Context

• Upgrading from 0.23.2 -> 0.25.0
• Cloudflare Workers build (not pages)
• Using react-compiler
• My project is quite large & complex. I'd reached the point where I'd have to build locally and manually deploy the artifact, because trying to build in Cloudflare via CI/CD was resulting in OOM errors. So the timing of Waku's integration with the Vite RSC plugin & Rolldown is perfect for me.
• The main challenge I faced with the upgrade was the error messages being very opaque and only hinting vaguely at some issue related to Node builtins (cryptic messages about path, require, etc.). There was no clear indication which dependency was causing the issue (turns out there were a few).

package.json

Amongst other things, I used the following pnpm overrides setup for the upgrade. I'm not entirely sure if it is even necessary as Waku already uses @vitejs/plugin-react v5 - which I think now uses Rolldown by default? Anyway, it ensures that the environment is as consistent as possible.

      "@vitejs/plugin-react": "5.0.0",
      "react": "19.1.1",
      "react-dom": "19.1.1",
      "react-server-dom-webpack": "19.1.1",
      "vite": "npm:rolldown-vite@latest",

waku.config.ts

Here's the main fix I needed for the nastiest build & server runtime errors:

            ssr: {
                resolve: {
                    conditions: ["import", "module"]
                },
                build: {
                    rolldownOptions: {
                        platform: "neutral"
                    }
                }
            },
            rsc: {
                resolve: {
                    conditions: ["import", "module"]
                },
                build: {
                    rolldownOptions: {
                        platform: "neutral"
                    }
                }
            }

I discovered the platform option from this comment.

Before upgrading Waku/Vite RSC plugin/Rolldown, whatever heuristic my npm deps were using to detect if they were building for Cloudflare Workers seemed to work by default. With the Vite environment API, however, setting it to "neutral" appears to be essential for ensuring that deps with multi-env build configs correctly detect that they're building for Cloudflare's workerd environment. Also note that I added resolve.conditions but this probably isn't necessary.

React Compiler

I just copied the solution from here (thanks again!) Add it to vite.plugins in waku.config.ts:

import react from '@vitejs/plugin-react'

react({ babel: { plugins: ['babel-plugin-react-compiler'] } })
  .map(p => ({ ...p, applyToEnvironment: e => e.name === 'client' }))

Other Notes

• Previously, I had build.rollupOptions.treeshake.moduleSideEffects: false in my Vite config. This was a needle in the haystack and caused a runtime error __vite_rsc_require__ is not defined when upgrading. Removing this option fixed the error.
• I have a custom Vite plugin which used a dynamic import inside the config hook. This stopped working but didn't affect the build. This is because the module runner lifecycle for plugins has changed in rolldown.
• The one dependency I am still struggling with is the Stripe SDK. I use it in a server action and get require related errors at build time. For now I've just commented it out to get a working build.

Final Thoughts

• Waku was already awesome, but it's even better now with the official Vite RSC plugin + Rolldown. Benefits are immediately clear in a resource-constrained environment like Cloudflare Workers. My builds no longer time out or fail due to OOM errors.
• Highly recommend everyone to try the latest Waku version if you haven't already! Thanks again for a great framework

[hi-ogawa]

Awesome! thanks for sharing the journey of upgrade! May I ask a few things?

• for build, do you use waku build --with-cloudflare or something else on your own after normal waku build?
• during dev, how do you integrate cloudflare bindings? Does it use similar pattern as this example https://github.com/wakujs/waku/tree/main/examples/07_cloudflare?
• do you have build perf stats about before and after the migration? How long did it took? How many modules are bundled? (the build log should show ✓ xxx modules transformed)

---

waku.config.ts

rolldownOptions.platform: "neutral" is necessary for non-node environment build. Waku should automatically configure this on --with-cloudflare on rolldown-vite.

react compiler

We changed @vitejs/plugin-react side to enable react compiler only on client build since v5.0.1, so you can remove applyToEnvironment workaround https://github.com/vitejs/vite-plugin-react/releases/tag/plugin-react%405.0.1

The one dependency I am still struggling with is the Stripe SDK. I use it in a server action and get require related errors at build time. For now I've just commented it out to get a working build.

If it's working before, it should be possible to make it work. Can you provide a reproduction?

[hi-ogawa]

Actually there was also a bug on latest rolldown-vite which breaks server action and potentially some other things #1625. Which version of rolldown-vite@latest do you use?

[jkhaui]

Awesome! thanks for sharing the journey of upgrade! May I ask a few things?

• for build, do you use waku build --with-cloudflare or something else on your own after normal waku build?

• during dev, how do you integrate cloudflare bindings? Does it use similar pattern as this example https://github.com/wakujs/waku/tree/main/examples/07_cloudflare?

• do you have build perf stats about before and after the migration? How long did it took? How many modules are bundled? (the build log should show ✓ xxx modules transformed)

---

waku.config.ts

rolldownOptions.platform: "neutral" is necessary for non-node environment build. Waku should automatically configure this on --with-cloudflare on rolldown-vite.

react compiler

We changed @vitejs/plugin-react side to enable react compiler only on client build since v5.0.1, so you can remove applyToEnvironment workaround https://github.com/vitejs/vite-plugin-react/releases/tag/plugin-react%405.0.1

The one dependency I am still struggling with is the Stripe SDK. I use it in a server action and get require related errors at build time. For now I've just commented it out to get a working build.

If it's working before, it should be possible to make it work. Can you provide a reproduction?

Thanks for sharing the key info! I would have gone crazy trying to figure it out otherwise.

• Yep, using the standard waku build --with-cloudflare. I run some babel plugins during build to compress the final size below the 3mb free tier limit on Cloudflare, but otherwise it's all conventional
• Yep exactly the same as the template! Thanks to @rmarscher for the reference example
• Sure, I'm on my phone atm so I'll gather some perf metrics tomorrow. I'm curious as well. Previously the build would timeout (exceed 20 mins) and/or run out of memory. Now it builds within 5-10 mins. So the numbers will be good 😃

Actually there was also a bug on latest rolldown-vite which breaks server action and potentially some other things #1625. Which version of rolldown-vite@latest do you use?

I'll check this tomorrow as well, but this was all done within the last couple of days - so unless there's been a recent release it should be whatever the current version is