From d6d48287c05d190f93a2bab97bbdc224d75d36f6 Mon Sep 17 00:00:00 2001 From: wang5333 Date: Wed, 1 Jul 2026 14:15:45 +0800 Subject: [PATCH] docs: document ssr noExternal for custom themes --- docs/en/guide/custom-theme.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/docs/en/guide/custom-theme.md b/docs/en/guide/custom-theme.md index 8de4c7ab..04144425 100644 --- a/docs/en/guide/custom-theme.md +++ b/docs/en/guide/custom-theme.md @@ -222,6 +222,25 @@ export default { } ``` +If the external theme package imports VitePress or Vue files that need to be +compiled during build, add the package name to Vite's `ssr.noExternal` option. +Use the package name that appears in your theme import, not a Vue component +name. This allows Vite to bundle the theme package for SSR instead of loading +it directly from `node_modules`. + +```ts [.vitepress/config.ts] +export default { + vite: { + ssr: { + noExternal: ['awesome-vitepress-theme'] + } + } +} +``` + +This can help when `vitepress dev` works but `vitepress build` fails with an +`ERR_MODULE_NOT_FOUND` error for files imported through a distributed theme. + Finally, if the theme provides types for its theme config: ```ts [.vitepress/config.ts]