Vite SSR "Cannot read properties of undefined" - Externalize Deps
In an SSR build, Vite externalizes most dependencies (leaves them as runtime require/import) by default. When a dependency must be transformed by Vite to work under SSR - or one that should stay external is bundled - the server build throws at import or render time.
What this error means
A Vite SSR build or vite-node/framework SSR run fails with an import-time crash (Cannot read properties of undefined, default is not a function, require is not defined) tied to one dependency. It works in the client build but not on the server.
TypeError: Cannot read properties of undefined (reading 'createElement')
at Module.render (/app/node_modules/some-ui-lib/dist/index.cjs.js)
at renderToString (/app/dist/server/entry-server.js)
[vite] Error when evaluating SSR moduleCommon causes
A dep needs Vite transform under SSR
Some packages (CSS-in-JS, libraries shipping ESM-only or needing interop) break when externalized for SSR. They must be added to ssr.noExternal so Vite bundles and transforms them for the server.
A native/runtime-only dep was bundled
Conversely, a package with native bindings or that reads __dirname/files at load can break when Vite tries to bundle it for SSR; it must be kept external.
How to fix it
Control externalization explicitly
Use ssr.noExternal to bundle a dep, or ssr.external to keep one external.
// vite.config.ts
export default defineConfig({
ssr: {
noExternal: ['some-ui-lib'], // bundle + transform for SSR
external: ['better-sqlite3'], // keep native dep external
},
})Diagnose which side the dep belongs on
- If the error is missing interop / ESM evaluation, add the dep to
ssr.noExternal. - If it is a native binding or filesystem-at-load package, add it to
ssr.external. - Reproduce with the SSR build in CI, not just the client build.
How to prevent it
- List SSR-incompatible deps in
ssr.noExternaldeliberately. - Keep native/runtime-only deps in
ssr.external. - Run the SSR build in CI so externalization bugs fail before deploy.