Docs: explain how to do node polyfills

[mtmacdonald]

Documentation is

• Missing
• Outdated
• Confusing
• Not sure?

Explain in Detail

Hi! Can we please have some docs on how to do node polyfills in modern (Rolldown) vite?

I understand the project's decision not to do this automatically (since frontend packages should not be relying on node functions). But in reality, not all mainstream NPM packages have caught up, and node polyfills are still sometimes needed.

I think many in the community are relying on the vite-plugin-node-polyfills NPM package, but my impression is it's not being actively maintained or upgraded for rolldown-vite and Vite 8 (e.g. see recent bug tickets on security, optimizeDeps.esbuildOptions warnings, runtime error regression).

I've also seen projects using:

• rollup-plugin-node-polyfills (presumably only relevant for production builds in older pre-rolldown versions of Vite)
• @esbuild-plugins/node-modules-polyfill and @esbuild-plugins/node-globals-polyfill, via optimizeDeps.esbuildOptions.plugins (presumably only relevant for dev server builds in older pre-rolldown versions of Vite)

And recently found

• rolldown-plugin-node-polyfills, but it wasn't immediately clear to me if that's directly usable in Vite, or if it applies to both PROD and DEV builds.

Currently all I can find in the Vite docs is this statement, but no tips on how.

Your Suggestion for Changes

Could we please have an example / recommendation in the docs on how to add a polyfill for a node dependency (e.g. Buffer). That would really help me unblock two projects if vite-plugin-node-polyfills doesn't get some maintenance for Vite 8 support. Thank you!

Reproduction

https://vite.dev/guide/troubleshooting#module-externalized-for-browser-compatibility

Steps to reproduce

N/A (docs update request)

[monam2]

As I understand it, Vite intentionally does not provide Node.js API polyfills by default, since they are not part of the browser platform.

That makes sense, but in practice users often run into this when dependencies rely on Node globals like Buffer or process, and it’s not very clear from the docs how this is expected to be handled.

It might help to add a small section to the docs (e.g. Troubleshooting or Guides) that briefly explains this stance and outlines common community approaches (using plugins, alias/define, or avoiding Node-only deps), without officially recommending a specific solution.

If this sounds reasonable, I’d be happy to help with a small docs PR.

[mtmacdonald]

@monam2 thank you. I understand the Vite project doesn't want to handle node polyfills directly, or take official positions on particular plugins (makes sense).

But having some tips, guidelines, and examples would still be very helpful.

In addition to the links in the description, I found rolldown-plugin-node-polyfills, but it wasn't immediately clear to me if that's directly usable in Vite, or if it applies to both PROD and DEV builds.