Preparing SSR for General Availability: Problematic Dependencies and API Improvements

[GrygrFlzr]

Currently, Vite SSR is marked as experimental. The core team perceives the biggest blocker to be a significant number of dependencies which do not work out of the box, requiring manual configuration of Vite's dependency resolution to get working. While it is inevitable that we cannot cover for every possible dependency and configuration, the majority should "just work" before Vite SSR should be considered non-experimental.

Examples of modules that encounter issues include:

• AWS SDK
• Firebase
• GitHub Octokit

In order to get SSR to general availability, we would like to:

1. Collect feedback from SSR/SSG plugin authors about potential improvements to Vite's SSR API.
   • If there's anything missing that would be of great help for implementing SSR with Vite, it'd be good to discuss them here.
2. Compile a community database of dependencies which do not work out of the box with Vite SSR.
   • We would like to be able to identify common issues across problematic dependencies in order to improve Vite's SSR resolution algorithm. Temporary workarounds are also welcome in order to better assess the situation.
   • Different SSR solutions will stress different pain points. React/Vue SSR may not hit the same issues as Svelte SSR and vice versa.
   • There are other dependency resolution issues which can be blocker for specific dependencies, (e.g. d3 and cyclic dependencies), but this list will focus only on ones that occur during SSR.
3. Document optimizeDeps and ssr options better.
   • In particular, optimizeDeps.include, optimizeDeps.exclude, ssr.noExternal, and ssr.external tend to be unclear to most people.

// cc @axe-me @brillout @dominikg @DylanPiercey @egoist @frandiox @g-plane @kiaking @LinusBorg @marvinhagemeister @meteorlxy @ryansolid @Subwaytime @TomokiMiyauci @wheatjs

TL;DR

Please respond to this discussion if you are either:

• Able to provide specific reproduction of a dependency having issues in SSR
• Are an SSR/SSG implementor and require features to be implemented into Vite's core SSR functionality

Click here to submit problematic dependencies

Click here to view the SSR Dependency Database (added soon)

[brillout]

significant number of dependencies which do not work out of the box

I'm wondering; if all server dependencies are externalized, what exactly is the problem here? Why should I want Vite to transpile the AWS SDK? Wouldn't I want to externailize and let Node.js use it directly instead?

For example #1374 (comment) is not really a SSR problem but more a browser-transpiling problem. If anyhting it's a Vite core problem (not transpiling Node-only builtins) but certainly not a Vite SSR problem.

Or is it about being able to have fine-grain control over what is treated as "Browser code that should be transpiled" VS "Node.js code that should be externalized"?

[brillout]

@frandiox A CLI flag --bundle-all instead of a new commend vite bundle-server makes sense 👍

[aleclarson]

I don't see the reason to have Mode 1 at all. Mode 2 supports all deployment strategies, so I don't see the need to complicate things. Of course, changing SSR behavior from Mode 1 to Mode 2 would be a breaking change.

[brillout]

@aleclarson

If we were to go all-in with Mode 2, then we'd also bundle all server-side dependencies for dev. That would slow down dev by several orders of magnitude, as dependency-code is several orders of magnitude larger than user-code. So we should have Mode 1 for dev at least.

But even for prod, I believe we want to have a Mode 1. We cannot assume that Vite will (let alone can) bundle in the likings of all deployment providers. Now the user can use the Vite bundler and additionally use the deloyment provider's bundler, but that would be wasteful and I can see Vercel users to wonder "Why would I want to use the Vite bundler if Vercel already bundles my code for me anyways? I don't want Vite to bundle for me."

Hence my proposal to go all-in with Mode 1. In other words:

• Every dependency is externalized by default. (We can still add some exceptions for Svelte libraries that need to be transpiled.)
• Vite should not try to resolve dependencies (which often causes problems) ([SSR] Stop resolving externalized dependencies #4340)

For prod, the user can opt-in to use the Vite SSR Bundler (Mode 2).

$ vite build --ssr --bundle

[aleclarson]

If we were to go all-in with Mode 2, then we'd also bundle all server-side dependencies for dev.

I don't think that's a given. The serve and build commands are two different things.

We cannot assume that Vite will (let alone can) bundle in the likings of all deployment providers.

Why not? A bundle is literally just a single JS module with no imports.

Now the user can use the Vite bundler and additionally use the deloyment provider's bundler, but that would be wasteful and I can see Vercel users to wonder "Why would I want to use the Vite bundler if Vercel already bundles my code for me anyways? I don't want Vite to bundle for me."

Why would a Vercel customer use Vite in the first place? Isn't Vite SSR for roll-your-own solutions?

Regardless, if a provider requires their bundler be used as well, it's not that big a deal, IMO. There's always room for provider-specific plugins that make Vite mimic their bundler, removing the need for it.

[brillout]

I don't think that's a given. The serve and build commands are two different things.

Ok so we agree that Vite should do Mode 1 for dev.

Why would a Vercel customer use Vite in the first place? Isn't Vite SSR for roll-your-own solutions?

SSR merely denotes the practice of rendering pages to HTML on the server-side. How you deploy your Node.js app is orthogonal to whether your Node.js app renders pages to HTML or not. (There are actually many users deploying Vite SSR apps to Vercel.)

Why not? A bundle is literally just a single JS module with no imports.

I'm not sure but I believe it's more complicated than that. E.g. what GrygrFlzr wrote here:

For example, Netlify's zip-it-and-ship-it bundler constantly chokes on node_fetch 2.x

But honestly I don't know why it chokes and I wouldn't why it does. In principle I'd agree that there would be nothing opinionated about bundling server-code. I mean if Vite uses require.resolve() and externalizes Node.js native modules, I wouldn't know what opinions there could be here.

Still, I'd still argue that a Vite user should be able to not bundle. Whether it's opt-in or opt-out I don't really mind. There are many deployment environments (probably most of them actually) where the user doesn't need his server-side code to be bundled. (Docker, AWS EC2, Vercel, etc.)

There are Node.js libraries that cannot be bundled. E.g. a Node.js library that does this:

require(determineRequirePathAtRunTime());

[brillout]

Are an SSR/SSG implementor and require features to be implemented into Vite's core SSR functionality

From my perspective, only two things are missing for a perfect Vite native SSR API.

1. Better handling of the server entry — vite path/to/server.js

Something like

vite path/to/server.js

which would automatically handle the whole vite.loadSSRModule dance, including server HMR (more precisely speaking server auto-reload).

For example, the playground's server file playground/ssr-vue/server.js is not processed by Vite which means:

1. If the user makes a change to server.js then she has to manually stop and re-start the server.
2. The user cannot use things like import.meta.env.
3. The user cannot use TypeScript nor ES6 Modules without using an extra tool such as ts-node.

It would be super convenient if the user can $ vite path/to/server.js and have all these features to just work.

This would not only be convenient for people building apps using the Vite native SSR API directly, but also for vite-plugin-ssr users (and other frameworks such as Vike).

This has been the number one pain for vite-plugin-ssr users. They get confused that server.js is not processed by Vite. (The boilerplate $ yarn create vite-plugin-ssr showcases a similar situation than playground/ssr-vue/ and playground/ssr-react/.)

2. Better handling of HTML-only + assets — ?assets

I'm super interested in rendering apps to HTML with minimal/zero browser-side JavaScript. (And the community apparently as well; see the hype around Astro Build.)

For example, with vite-plugin-ssr, you can do this:

// _default.page.server.js
// Environment: Node.js

import { renderToHtml } from 'my-favorite-view-framework'
import logoUrl from '../images/logo.svg'
import { html } from 'vite-plugin-ssr'

export async function render(pageContext) {
  const pageHtml = await renderToHtml(pageContext.Page)
  return html`<!DOCTYPE html>
    <html>
      <head>
        <link rel="icon" href="${logoUrl}" />
      </head>
      <body>
        <div id="page-root">${html.dangerouslySkipEscape(pageHtml)}</div>
      </body>
    </html>`
}

// _default.page.client.js
// Environment: Browser

// This file is empty which means there is zero browser-side JavaScript.

This works with the exception that logo.svg is missing in dist/ (it's not in dist/client/ since vite build is not aware of the existence of _default.page.server.js and it's not in dist/server/ since vite build --ssr ignores browser-side assets).

A solution for the user is to import logo.svg (and all other browser assets) in _default.page.client.js

// _default.page.client.js
// Environment: Browser

+ // List of all browser assets
+ import '../images/logo.svg'
+ // ...
+ 
// This file is empty which means there is zero browser-side JavaScript.

But it becomes cumbersome to maintain the list of all browser assets.

A better solution would be to have a flag _default.page.server.js?assets that would skip all code and only retrieve browser assets.

The user can then

// _default.page.client.js
// Environment: Browser

+ import './_default.page.server?assets'
+ 
// This file is empty which means there is zero browser-side JavaScript.

And better yet the framework would automatically add _default.page.server?assets to build.rollupOptions.input so that things just works for the user.

This would be crucial for any framework pushing the HTML-first trend forward, e.g. React Server Components. (With React Server Components, React users will be able to have only a couple of client-side components while the rest of the app is server-side only.) I'd love to offer a Vike petite-vue + Vue SSR boilerplate and a React Server Components boilerplate.

If something's not clear let me know; I'm happy to elaborate.

[spacedawwwg]

☝🏻 all of this!

[Aslemammad]

With ssrLoadModule, the resolveId doesn't get called sometimes (like react). That's where I want to do some extra stuff to handle that. I know it's expected, but It makes things harder.
#3609

[benmccann]

Something that's quite unclear to me from the docs is the part about dependency pre-bundling. The docs make no mention of whether this is for the client-side only or includes the server-side. It seems to me that it might be only the client-side because the behavior is very different between the client and server. It would be nice if the server could simply use the prebundled ESM the same way that the client does because it's frustrating to have the client working and the server broken eventhough they're using the same packages

[benmccann]

Evan answered this on Discord: https://discord.com/channels/804011606160703521/921428591739281438/921921653150191636

[yeyan1996]

Evan answered this on Discord: https://discord.com/channels/804011606160703521/921428591739281438/921921653150191636

I didn't find the reply in your link，can you tell me the content of the reply? thx

[dominikg]

pure esm packages currently don't work without ssr.noExternal + optimizeDeps.exclude

should be documented and if possible either handled automatically or at least add a helpful error message

#3273 (comment)

https://github.com/vitejs/vite/blob/main/packages/vite/src/node/ssr/ssrModuleLoader.ts#L92

vite/packages/vite/src/node/ssr/ssrExternal.ts

Line 11 in 887c247

* TODO right now externals are imported using require(), we probably need to

[aleclarson]

Related PR: #4450

[frandiox]

Another thing that perhaps should be resolved before marking SSR as production ready is CSS injection during SSR: #2282

There are workarounds for user-land but I would expect Vite to handle this if it's production ready 🤔

[brillout]

Good point, there should be an official way of doing it that is united tested.

[benmccann]

Here's a bug that I've done some preliminary investigation into and should be fixed as part of these efforts: https://github.com/vitejs/vite/issues/4113

[milky2028]

Is there a temporary solution currently to deal with problematic dependencies?

[cor]

Also curious about this. I'd especially like a workaround for firebase

[benmccann]

I did some more digging on Firebase and uncovered a new Vite SSR issue: #4425

[milky2028]

Right now, with Sveltekit, my alternative is to just set ssr: false in svelte.config.js. The current breaking behavior with the v9 Firebase beta is only breaking with SSR in dev mode, not in production for me, so disabling SSR for dev unblocks my workflow. I still get errors, but my app works.

[leafOfTree]

Is it possible to automatically find out problematic dependencies?
For example, we can write a tool to install the top 1000 most popular npm packages in React/Vue/Svelte environment one by one. And then try to run it to see if it works.

[ivanhofer]

Another SSR bug: #4452

[benmccann]

I created a list of the Vite issues that SvelteKit users most often hit: sveltejs/kit#2086

[mlrawlings]

One other consideration with ssr.transpile: the idea here is that we can transpile files that are loaded from external files. These external files can be common js andrequire is a synchronous api, but transform can be an async function.

I'm not sure how ssr.noExternal currently works though. Maybe this is already a solved problem?

[benmccann]

A big part of the issue is that pre-bundling happens with esbuild and the normal Vite build happens with Rollup. esbuild is written in Go and historically hasn't supported plugins. Perhaps that's changing a bit as I do see a Svelte esbuild plugin exists now.

Svelte is new enough that basically all Svelte packages are written in ESM, so we don't actually need them to be pre-bundled. The big issue we have is that a lot of them have CJS dependencies and their dependencies aren't being pre-bundled. I sent a PR to address that (#4552) and we're also planning to detect Svelte packages and automatically exclude them from optimization. I think once those items are addressed the big issues for us will mostly all be related to SSR.

[mlrawlings]

A big part of the issue is that pre-bundling happens with esbuild and the normal Vite build happens with Rollup. esbuild is written in Go and historically hasn't supported plugins. Perhaps that's changing a bit as I do see a Svelte esbuild plugin exists now.

That's what I mean by the transform plugin hook only applying to 2 of the 4 ways a file gets loaded. It's ignored for esbuild and the node module system (ssr.external). A regex as proposed for ssr.transpile could be used for an esbuild load hook as in the svelte plugin you mentioned. That's a key piece precisely because esbuild is written in Go and coming back to JS for every file would tank performance.

Svelte is new enough that basically all Svelte packages are written in ESM, so we don't actually need them to be pre-bundled.

Unfortunately this is not the case with Marko. We're 100% fine with requiring ESM for code within the application, but not supporting packages that use both Marko and CommonJS makes us hesitant to recommended Vite as the default setup (both in eBay and externally).

Even if skipping prebundling for Svelte packages works, as I mentioned above, it's really just a workaround. If it worked properly, is there any reason you wouldn't prefer those packages to be prebundled?

[benmccann]

I'm not sure I caught everything in the first part of what you said. I started a Discord channel so that we can chat about implementation details further: https://discord.com/channels/804011606160703521/874487184504270888

There are lots of Svelte packages with CJS deps and we should support those. But I almost think it's a benefit to the community to disallow Svelte packages themselves to be written in anything other than ESM. There's no reason why someone should be writing a Svelte package in anything else in 2021. I can't recall ever seeing one in the wild, so it'd be a very low impact change. It'd make the tooling simpler and give us fewer cases to test against.

I don't understand the difference between saying a Marko application should be written in ESM and saying a Marko package should be written in ESM. We need to support CJS deps, but are there popular Marko libraries written in CJS? It wouldn't make sense to me to use a server-side file include method in a UI framework that runs in the browser

[benmccann]

Here's an issue with a lot of detail on potential paths forward for pre-bundling: #3910

[axe-me]

Sorry I'm late to the party, hopefully not too late. After skimming through some comments above, I just want to add up some of my opinions on config API improvement for SSR mode from my experiences of making the vite-node-plugin

1. Enable the HTTP server in SSR mode

• SSR mode always needs to run a server anyway, no point to disable the HTTP server then let user create their own server. Plus, vite itself already has a set of configs for the HTTP server. We may need to disable some middlewares made for serve mode.

2. Allow user to add middlewares to the HTTP server

• After the builtin http server is enabled, we still need to pass down all the requests to the renderer. This means we need to add a NEW config option to allow user to add a middleware to get all the requests.

3. framework adapters

The request object from vite http server is compatible with connect-like frameworks. However, it may require some extra works to let other frameworks like fastify to handle it. We can either write some documents for it or write some official adapters.

In fact, I kinda already doing this in the vite-node-plugin, except I have to create my own http server. If you like my idea, I can just port all those logic back to vite easily. you can take a look how is the plugin works at this repo

This approach should resolve the problem 1 from @brillout 's comment #4230 (comment)

[axe-me]

And this is basically what the vite-node-plugin is doing. You can take a look at the code https://github.com/axe-me/vite-plugin-node/blob/main/src/server/index.ts#L56 if my explanation is still unclear to you.

[benmccann]

Ok, if I understand correctly, there are a couple nice things that would enable. E.g. if the user wants to add custom middlewares, Vite could load changes to them whereas that might be harder if we were managing our own server outside of Vite. Also, I have seen users get confused between the Vite server config and our own. Having only one set would simplify some things

I think we should be able to keep our CLI and just call Vite's createServer

One thing that's a bit of a pain for us right now is the server.hmr.server configuration option. It forces a circular reference between our server and the Vite server. I suppose that pain point would probably go away with only one server, which would be another nice reason to do it

[benmccann]

I looked a bit at trying to use Vite's server instead of creating our own and using the middleware mode. The main thing that's a bit hard is that it looks like Vite expects the entry point to be an index.html file when using the Vite server. We don't have that, but instead have a src/app.html with %svelte.head% and %svelte.body% placeholders and I'm not sure how those would be handled. Our JS entry points don't even live in the user's project, but are generated, so it doesn't really mesh well with the index.html setup

[benmccann]

@axe-me it actually looks like you can probably mostly do this today with configureServer: https://vitejs.dev/guide/api-plugin.html#configureserver

[axe-me]

@benmccann You are right! my bad, I didn't think about using that option to do all this. I guess all we need to add is the ability to config builtin middleware, disable some of them etc.. I saw your PR, that's a good start! Thanks for your work!

[ryansolid]

Not sure if this is the same as some of the issues that you've all been having but, in Solid JSX is treated special. We wrote a plugin that transforms .jsxfiles but the problem is this only works if the entry point of the package is .jsx. If a normal .js file re-exports from a .jsx file it gets handed to ESBuild which leaves us with React transformed JSX. Besides making package entries .jsx we've needed to add noExternal to SSR config to ensure they are handled properly on pretty much every 3rd party library.

It's a bit tedious. Not sure if the solutions here will address that but thought I'd share. I think the fact that the plugin transform only working on the package entry point is really obnoxious but I think that what I'm seeing is more of a combination of multiple issues more than any single one. Luckily Solid doesn't have the .cjs issue so much but I would think that nested imports being handled properly would be an expectation here.

Couldn't plugin transform just apply to everything?

[axe-me]

have you tried to use plugin order? https://vitejs.dev/guide/api-plugin.html#plugin-ordering
It can make sure your plugin runs before the core plugins.

[ryansolid]

It's not the order. It is that it only looks at the package entry. I suppose we could do something that analyze the package our self. But basically check if the entry is .jsx or .tsx then process it or leave it to Vite and ESBuild. I think there is probably other solutions to this, but it would be great if there was just a per file type filter. I can look for the custom export map field like the svelte field.

[bluwy]

Probably related, but packages with jsx/tsx entrypoints are excluded from prebundling by default, per 1857652. Normal js entrpoints will be prebundled. But technically, all solid libraries (with jsx/tsx) should be excluded from prebundling or it'll encounter #3910. For svelte, we're planning to auto-exclude svelte libraries manually per sveltejs/vite-plugin-svelte#125

Couldn't plugin transform just apply to everything?

Re plugin transform apply to prebundling, I think this comment could explain some problems (snowpack/esinstall applies transform for prebundling)

---

Otherwise if I'm misunderstanding the question, an issue or repro would be nice to explain the problem

[stefanvanherwijnen]

Is it correct that when resolving noExternal packages, resolve.alias is not used? I.e. I alias a package to a local folder's src folder, but the bundled code still contains the code from the ESM build in the dist folder.
If so, is there another way to build packages from source in a SSR build? For non-SSR builds aliasing the package name to the src folder works fine.

Edit: This actually seems to be a problem with aliasing subpaths which doesn't work correctly in the way I am using it.

[patak-dev]

Most issues with SSR deps seems to be resolved now in vite@2.7.0-beta.10, if you had some problems in your projects with previous versions it would be very helpful to test with this beta and create new issues for them if you still experience a problem

[awacode21]

SSR: Hydration mismatch

When following this example for ssr: https://vitejs.dev/guide/ssr.html & https://github.com/vitejs/vite/tree/main/packages/playground/ssr-vue

i always get hydration mismatch on dev server using base route http://localhost:3000/ as ist seems it never runs through the app.use('*', //some function) of express which would handle the ssr.

on prod build it's working fine.

any idea?