Documenting `vite.ssr.noExternal`

[mayank99]

Vite externalizes SSR dependencies by default: https://vitejs.dev/guide/ssr.html#ssr-externals

A lot of npm packages are not ESM-ready so it leads to errors when using ESM imports.

This can be fixed by forcing those packages to be transpiled by vite using vite.ssr.noExternal in astro.config

vite: {
  ssr: {
    noExternal: ['package-name']
  }
}

Since it's not obvious how to arrive at this solution (and vite's docs are a bit sparse), maybe this should be added somewhere in the astro docs, e.g. the troubleshooting section?

Also there are probably other cases for using vite.ssr.noExternal that I can't think of right now.

[Jutanium]

Looks like we name-drop it on the styling page, but deserves its own spot somewhere as there are other use cases. It also doesn't really explain what noExternal does

[Jutanium]

Docs team discussed; the remaining use case to document is when using a non-ESM package. We can note this in Troubleshooting and link from our static assets page

[delucis]

💡 Idea

How about we link from our “NPM Packages” section in the imports guide to the config reference section about Vite? We could then beef up the config reference to add some of the helpful context from @mayank99 and add a noExternal example.

[sarah11918]

@mayank99 Would you be interested in making a PR for this, by any chance?

[mayank99]

@sarah11918 Done! https://github.com/withastro/docs/pull/2254

Frankly, I do not fully understand what Vite does and what Astro does, so it would help if someone who better understands the vite externalization sorcery can review the PR.

[sarah11918]

Thank you, @mayank99 🙌

we'll let some Astro wizards handle the sorcery part. 🧙‍♂️ This is so helpful!