Removing legacy.proxySsrExternalModules

[bluwy]

legacy.proxySsrExternalModules

• Added in vite@5.0.0-beta.11
• Rationale in feat!: remove ssr proxy for externalized modules #14521
• To be removed in Vite 6

If you have concerns, questions, or bug reports as to why you still need this option, please leave a comment here!

---

Notes

1. This comment brought up that this option is still useful when outputting as CJS. In a CJS build, Rollup is able to bundle named imports of externalized CJS packages to something that works in a CJS runtime.

   Our dev runtime usually don't take in account of build-related settings, and unfortunately we had removed ssr.format: 'cjs' that would've allowed us to avoid checking build-related settings, but I think this may be an exception for now to get CJS somewhat working.

[sadiqsalau]

I'm importing some packages such as react-slick or react-fast-marquee, during build it works fine but throws error during SSR due to Vite exporting the module twice without this option..

vite.ssrLoadModule("...")

[Module: null prototype] {
  __esModule: true,
  default: { default: [Function: Slider] }
}

How to fix this without enabling this option?

[sadiqsalau]

Came up with a fix!

import __Slider from "react-slick";

const Slider = __Slider.default || __Slider;

[bluwy]

@sadiqsalau I tested react-slick in Node.js, and it seems like Vite is correctly aligning with it. E.g. this code in Node.js:

import mod from 'react-slick'
console.log(mod) // -> { default: [Function: Slider] }

And

console.log(await import('react-slick'))
// -> [Module: null prototype] {
//   __esModule: true,
//   default: { default: [Function: Slider] }
// }

If it works during build, could it be that you're bundling it during builds? E.g. if you have ssr.noExternal: true (bundle all deps), or ssr.noExternal: ['react-slick'], that means the library will be bundled.

[sadiqsalau]

Yes I'm bundling everything during SSR builds.. But while testing SSR during development, I get double export

[bluwy]

Yeah, in that case I think this is expected. The dependency is handled by Node.js in dev, and by Vite in build, so an inconsistency is expected here without Vite guessing the environment between dev and build.

Using const Slider = __Slider.default || __Slider; is the more appropriate solution for me for now then, compared to enabling the legacy option. Or you can also add the dependencies to ssr.noExternal so it's properly detected in dev (however the dep needs to be in ESM).

[sai-cb]

In case this feedback is helpful;

That I could experience, the ecosystem's state for node.js likely does not fit this removal well.

• Packages routinely only support CJS.
• Published types of packages tend to (inaccurately) assume interop.

So a few key points come to mind:

ESM without interop may be unrealistic

For any server project of a decent size, the task of writing strict ESM (without interop) may be too error-prone and require too much maintenance to be viable because of historical node.js and typescript decisions.

Providing interop support would match browser builds:

That's solution 1 (Make prod match dev behaviour). Although I understand supporting externalized dependencies may carry different challenges, the final dev experience would be more consistent for Vite users across browser and ssr builds.

CJS builds need legacy.proxySsrExternalModules

Projects that still compile to CJS (as I suspect may be common for node.js projects) were not affected by this dev vs prod discrepancy and using legacy.proxySsrExternalModules seems still appropriate for these cases.

By CJS builds, I mean this:

build: {
  rollupOptions: {
    output: {
      format: 'cjs',
    },
  },
},

[bluwy]

Thanks for the explanation. After making some tests, I agree that when outputting CJS, legacy.proxySsrExternalModules seems to work best here. In which case, perhaps we can auto-enable the option internally if you're outputting as CJS, but still remove the legacy option in the next major so it's not possible to use it for ESM outputs.

Making this change will be breaking, so I'll note this in the discussion description above so we'll implement the behaviour in the next major.

[remorses]

@bluwy another use case where proxySsrExternalModules is useful is when passing ssr.noExternal: true. There is no mismatch in this case between prod and dev.

[bluwy]

I think it should already be the case today regardless of the option. The option only deals with externalized modules.

[remorses]

Forgot to reply here. I only pass noExternal: true when building, in development i keep it undefined so it's faster.

Please don't remove proxySsrExternalModules, it makes interopability with commonjs packages much simpler

[sai-cb]

One slight update here; Support for proxySsrExternalModules is no longer relevant in my case.

My initial comments were based on the assumption that adopting ESM with node.js and Vite was a risky enterprise, and using CJS was the only safe option as of now...

However with the recent realization that node.js cannot import ESM modules inside a CJS module without runtime crashes, and more and more libraries are publishing as ESM only, it seems like neither CJS nor ESM are truly manageable.

So with that in mind, it seems realistic to me that Vite would keep moving forward with deprecating CJS.

However, in an ideal world, a lot more safeguards would be in place in Vite to make ESM safer.

I moved the topic of safeguards in the following discussion: #17665

[remorses]

I don't understand why Vite can't do this transformation const Slider = __Slider.default || __Slider; automatically, there should be no difference between prod and dev, you just add that transformation in prod too

[remorses]

Can't you run the vite:import-analysys plugin during ssr? transforming the imports that are commonjs modules adding the following code:

// before
import Slider from 'react-slider'
// after
import __Slider from 'react-slider'
const Slider = __Slider.__esModule && __Slider.default ? __Slider.default :  __Slider;

This is what the user has to do anyway, so why not do it automatically and avoid TypeScript errors?

From what i understand you don't need to control modules loading to do this, you can do it as a transformation for files processed by Vite, tranforming the output of vite build --ssr

[bluwy]

1. It's not reliable to tell if the dependency if CJS. node --condition could change it.
2. If we unconditionally add the wrapper, not just default imports but also named imports, it breaks all ESM live bindings.
3. What if the dependency is re-exported?
4. How do we handle dynamic imports?
5. The issue still exists within dependencies not handled by Vite.

[remorses]

Thank you for responding, I wonder how other bundlers solve this, for example Next.js, which still externalizes server dependencies.

At first glance it seems they add a package.json with type: "commonjs" in the dist directory and bundle everything to commonjs, using import() for esm dependencies.

[remorses]

In my opinion this problem should have been solved in Node.js long ago, handling __esModule. Maybe it could still be done adding a flag. But telling people to add the .default workaround and break typescript types is the worst solution

[bluwy]

Yeah if Node.js also respected __esModule, that would be the most compatible. Though with what we have now, I wouldn't ask people to add .default as a workaround though, and instead request library maintainers to make it node-compatible if it's meant to be used in node. Vite has historically pushed libraries to properly package their code, and I think we can keep that going.

[getCryptoAddress]

Hi everyone,

Why I'm writing:

I recently upgraded my project to Vite 5 and found that I needed to use the legacy.proxySsrExternalModules flag. I'm reaching out because I’m concerned that I might still need this flag in the future, including with Vite 6.

My scenario:

Following the guide at https://vite.dev/guide/ssr#pre-rendering-ssg, I wrote a script to generate static pages for my site once during the build process.
You can see it here: prerender.mjs.
However, when I attempt to render the site (entry-server.ts), I encounter this error:

SyntaxError: [vite] Named export 'NMessageProvider' not found. The requested module 'naive-ui' is a CommonJS module, which may not support all module.exports as named exports.
CommonJS modules can always be imported via the default export, for example using:

import pkg from 'naive-ui';
const { NConfigProvider, NMessageProvider } = pkg;

What I expect:

I expect to have one codebase for both client and server, but legacy CJS libraries stop working only on the server side.

Thoughts:

Perhaps I am taking the wrong approach. If so, what would be a recommended way to generate both client and server parts with minimal differences?

[hi-ogawa]

Have you tried ssr: { noExternal: ["naive-ui"] }?

[sai-cb]

Alternatively the use of vite-plugin-cjs-interop (unofficial plugin) can help.

I've documented the issue here:
#17665

One risk with using noExternal is that a transitive dependency may also depend on naive-ui which would result in running two versions of the same library in the final production code.

This is particularly tricky with React providers, which the naming of this import (NMessageProvider) suggests is being used here.

I'm not sure if that is possible but ideally, Vite would automatically apply interop.

[getCryptoAddress]

@hi-ogawa
Thanks for the answer, yes, I tried different manipulations with build and ssr, including noExternal. But I could not achieve some positive result.

@sai-cb
Thanks. It is true. I tried vite-plugin-cjs-interop and it is help

But such roundabout ways scare me.

What I expect:

I expect to have one codebase for both client and server, but legacy CJS libraries stop working only on the server side.

Thoughts:

Perhaps I am taking the wrong approach. If so, what would be a recommended way to generate both client and server parts with minimal differences?

The gap between the client build and the SSR is slowly growing, not decreasing.

[bluwy]

Are you using vite build or the build() API for SSR? This option is meant to align the dev behaviour to build, otherwise you'd also get a similar error when running in build. If you're only using the dev server, then I could see how this option can still be useful in that context since the problem this option is trying to solve doesn't apply to your usecase.

When you have a client build that bundles all dependencies, and an SSR build that doesn't bundle all dependencies, some inconsistencies or special rules will happen like this case, and following the error, you should be doing

import pkg from 'naive-ui';
const { NConfigProvider, NMessageProvider } = pkg;

If that's tedious to do so, vite-plugin-cjs-interop looks like a decent alternative.