vitepress-spa-fallback 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 holazz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,22 @@
+# vitepress-spa-fallback
+
+Vite plugin for VitePress `2.0.0-alpha.20`. Adding it enables three build-time behaviors:
+
+- clear the home page `#app` after SSG, keeping the rest of the HTML;
+- load the full page module when that shell is empty; retry `hashmap.json` after a stale page-chunk failure;
+- rewrite root-relative static file URLs (`href` / `src` / `withBase`) to the resolved asset prefix.
+
+```ts
+import { defineConfig } from 'vitepress'
+import { vitepressSpaFallback } from 'vitepress-spa-fallback'
+
+export default defineConfig({
+  vite: {
+    plugins: [vitepressSpaFallback()],
+  },
+})
+```
+
+Runtime patches apply only to production builds. Other prerendered pages are left intact.
+
+Peer dependency is pinned to `vitepress@2.0.0-alpha.20`. The build fails if the expected runtime strings are missing, or if the plugin runs outside a VitePress build.

package/README.zh-CN.md

@@ -0,0 +1,22 @@
+# vitepress-spa-fallback
+
+面向 VitePress `2.0.0-alpha.20` 的 Vite 插件。加上即启用三件事：
+
+- SSG 结束后清空首页 `#app`，外围 HTML 不动；
+- 空壳加载完整页面模块；页面 chunk 过期时重试 `hashmap.json`；
+- 把根路径静态资源（`href` / `src` / `withBase`）改到最终解析的资源前缀。
+
+```ts
+import { defineConfig } from 'vitepress'
+import { vitepressSpaFallback } from 'vitepress-spa-fallback'
+
+export default defineConfig({
+  vite: {
+    plugins: [vitepressSpaFallback()],
+  },
+})
+```
+
+运行时补丁只在生产构建生效。其他预渲染页面保持原样。
+
+peer dependency 锁定 `vitepress@2.0.0-alpha.20`。对不上预期运行时字符串，或不是 VitePress 构建，会直接失败。

package/dist/index.d.mts

@@ -0,0 +1,15 @@
+import { Plugin } from "vite";
+
+//#region src/index.d.ts
+
+/**
+ * 1. config: prefix type=public built URLs with assetsBase
+ * 2. configResolved: wrap buildEnd / transformHtml once (client and SSR share SiteConfig)
+ * 3. transform: patch withBase, empty-shell page modules, and hashmap retry
+ * 1. config：给 type=public 的构建 URL 接上 assetsBase
+ * 2. configResolved：挂一次 buildEnd / transformHtml（client 与 SSR 共用同一份 SiteConfig）
+ * 3. transform：补丁 withBase、空壳走完整页、hashmap 重试
+ */
+declare function vitepressSpaFallback(): Plugin;
+//#endregion
+export { vitepressSpaFallback };

package/dist/index.mjs

@@ -0,0 +1,206 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+//#region src/html.ts
+const RAW_TEXT_TAGS = new Set([
+	"script",
+	"style",
+	"textarea",
+	"title",
+	"xmp",
+	"iframe",
+	"noembed",
+	"noframes",
+	"noscript"
+]);
+/**
+* Clear only #app's contents without reserializing or changing surrounding HTML.
+* 仅清空 #app 内部，不重新序列化 HTML，保留外围内容与原有格式。
+*/
+function createFallbackHtml(html) {
+	const tags = /<!--[\s\S]*?-->|<![^>]*>|<\/?([a-z][\w:-]*)(?=[\s/>])(?:[^<>"']|"[^"]*"|'[^']*')*>/gi;
+	let divDepth = 0;
+	let appDepth = -1;
+	let contentStart = -1;
+	let contentEnd = -1;
+	for (let match = tags.exec(html); match; match = tags.exec(html)) {
+		if (!match[1]) continue;
+		const tag = match[1].toLowerCase();
+		if (match[0].startsWith("</")) {
+			if (tag === "div") {
+				if (contentStart >= 0 && contentEnd < 0 && divDepth === appDepth) contentEnd = match.index;
+				divDepth--;
+			}
+			if (tag === "body" && contentStart >= 0 && contentEnd < 0) throw new Error("[vitepress-spa-fallback] Unclosed #app in generated index.html.");
+			continue;
+		}
+		if (tag === "div") divDepth++;
+		const attributes = match[0].slice(1 + match[1].length, -1);
+		for (const attr of attributes.matchAll(/([^\s"'<>/=]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+)))?/g)) if (attr[1].toLowerCase() === "id" && (attr[2] ?? attr[3] ?? attr[4]) === "app") {
+			if (contentStart >= 0) throw new Error("[vitepress-spa-fallback] Duplicate #app in generated index.html.");
+			if (tag !== "div") throw new Error("[vitepress-spa-fallback] Expected a div for #app in generated index.html.");
+			contentStart = tags.lastIndex;
+			appDepth = divDepth;
+		}
+		if (RAW_TEXT_TAGS.has(tag)) {
+			const endTag = new RegExp(`</${tag}\\s*>`, "gi");
+			endTag.lastIndex = tags.lastIndex;
+			if (!endTag.exec(html)) throw new Error(`[vitepress-spa-fallback] Unclosed ${tag} in generated index.html.`);
+			tags.lastIndex = endTag.lastIndex;
+		}
+	}
+	if (contentStart < 0 || contentEnd < 0) throw new Error("[vitepress-spa-fallback] Missing or unclosed #app in generated index.html.");
+	return html.slice(0, contentStart) + html.slice(contentEnd);
+}
+
+//#endregion
+//#region src/url.ts
+const ASSET_EXTENSIONS = "css|js|mjs|json|svg|png|jpe?g|gif|webp|ico|woff2?|ttf|otf|eot";
+const ROOT_ASSET_RE = new RegExp(`^/(?!/).+\\.(?:${ASSET_EXTENSIONS})(?:[?#].*)?$`, "i");
+const HTML_ASSET_RE = new RegExp(`\\b(href|src)=("|')(/(?!/)[^"'?#]+\\.(?:${ASSET_EXTENSIONS})(?:[?#][^"']*)?)\\2`, "gi");
+const EXTERNAL_URL_RE = /^(?:[a-z][a-z\d+\-.]*:|\/\/)/i;
+/**
+* Join assetsBase and a file path without duplicating slashes.
+* 拼接 assetsBase 与文件路径，避免重复斜杠。
+*/
+function joinAssetUrl(assetsBase, path) {
+	return `${assetsBase.endsWith("/") ? assetsBase.slice(0, -1) : assetsBase}${path.startsWith("/") ? path : `/${path}`}`;
+}
+function isRootAssetPath(path) {
+	return ROOT_ASSET_RE.test(path);
+}
+/**
+* Root-relative files go to assetsBase; page routes stay on site base.
+* 根路径静态文件改到 assetsBase，页面路由仍走站点 base。
+*/
+function rewriteAssetUrl(path, assetsBase, pageBase = "/") {
+	if (!assetsBase || EXTERNAL_URL_RE.test(path) || path.startsWith(assetsBase)) return path;
+	const prefix = pageBase === "/" ? "" : pageBase.endsWith("/") ? pageBase : `${pageBase}/`;
+	const relative = prefix && path.startsWith(prefix) ? `/${path.slice(prefix.length)}` : path;
+	return isRootAssetPath(relative) ? joinAssetUrl(assetsBase, relative) : path;
+}
+/**
+* Rewrite root-relative href/src values in generated HTML.
+* 改写生成 HTML 中的根路径 href/src。
+*/
+function rewriteHtmlAssetUrls(html, assetsBase, pageBase = "/") {
+	if (!assetsBase) return html;
+	return html.replace(HTML_ASSET_RE, (match, attr, quote, path) => {
+		const next = rewriteAssetUrl(path, assetsBase, pageBase);
+		return next === path ? match : `${attr}=${quote}${next}${quote}`;
+	});
+}
+/**
+* Prefix Vite `type=public` URLs; leave `type=asset` unchanged.
+* 只改写 type=public 的构建 URL，不改 type=asset。
+*/
+function createRenderBuiltUrl(assetsBase, original) {
+	return (filename, context) => {
+		const originalResult = original?.(filename, context);
+		if (originalResult !== void 0) return originalResult;
+		if (context.type === "public" && assetsBase.value) return joinAssetUrl(assetsBase.value, filename);
+	};
+}
+
+//#endregion
+//#region src/runtime.ts
+const APP_MODULE = "/vitepress/dist/client/app/index.js";
+const ROUTER_MODULE = "/vitepress/dist/client/app/router.js";
+const UTILS_MODULE = "/vitepress/dist/client/app/utils.js";
+const LEAN_PAGE = "if (isInitialPageLoad) pageFilePath = pageFilePath.replace(/\\.js$/, \".lean.js\");";
+const HASHMAP_FETCH = "fetch(runtimeBase() + \"hashmap.json\")";
+const WITH_BASE = "return EXTERNAL_URL_RE.test(path) || !path.startsWith(\"/\") ? path : joinPath(runtimeBase(), path);";
+const WITH_BASE_PATCH = `return EXTERNAL_URL_RE.test(path) || !path.startsWith("/") || (__ASSETS_BASE__ && path.startsWith(__ASSETS_BASE__)) ? path : joinPath((__ASSETS_BASE__ && /\\.(?:${ASSET_EXTENSIONS})(?:[?#].*)?$/i.test(path) ? __ASSETS_BASE__ : runtimeBase()), path);`;
+/**
+* Require exactly one match in the pinned runtime instead of silently drifting.
+* 固定版本的运行时必须唯一命中补丁，避免内部代码变化后静默失效。
+*/
+function replaceOnce(code, search, replacement, id) {
+	const index = code.indexOf(search);
+	if (index < 0 || code.includes(search, index + search.length)) throw new Error(`[vitepress-spa-fallback] Expected one patch target in ${id}; check VitePress 2.0.0-alpha.20 compatibility.`);
+	return code.slice(0, index) + replacement + code.slice(index + search.length);
+}
+function normalizeModuleId(id) {
+	return id.split("?", 1)[0].replace(/\\/g, "/");
+}
+/**
+* Patch VitePress client modules. withBase also runs during SSR so prerendered URLs match the client.
+* 改写 VitePress 客户端模块；withBase 在 SSR 中也会执行，保证预渲染地址与客户端一致。
+*/
+function patchRuntimeModule(code, id, options, consumer = "client") {
+	const moduleId = normalizeModuleId(id);
+	if (moduleId.endsWith(UTILS_MODULE)) return replaceOnce(code, WITH_BASE, WITH_BASE_PATCH, moduleId);
+	if (options?.ssr || consumer !== "client") return;
+	if (moduleId.endsWith(APP_MODULE)) return replaceOnce(code, LEAN_PAGE, "if (isInitialPageLoad && document.querySelector(\"#app\")?.hasChildNodes()) pageFilePath = pageFilePath.replace(/\\.js$/, \".lean.js\");", moduleId);
+	if (moduleId.endsWith(ROUTER_MODULE)) return replaceOnce(code, HASHMAP_FETCH, "fetch((__ASSETS_BASE__ || runtimeBase()) + \"hashmap.json\")", moduleId);
+}
+
+//#endregion
+//#region src/index.ts
+const HOOKED = Symbol.for("vitepress-spa-fallback:hooks");
+/**
+* Empty the home page after the user's buildEnd hook.
+* 在用户的 buildEnd 之后清空首页。
+*/
+function wrapBuildEnd(siteConfig) {
+	const original = siteConfig.buildEnd;
+	siteConfig.buildEnd = async (config) => {
+		await original?.(config);
+		const file = join(config.outDir, "index.html");
+		let html;
+		try {
+			html = await readFile(file, "utf8");
+		} catch (error) {
+			throw new Error(`[vitepress-spa-fallback] Missing ${file}.`, { cause: error });
+		}
+		const shell = createFallbackHtml(html);
+		if (shell !== html) await writeFile(file, shell);
+	};
+}
+/**
+* Rewrite leftover root-relative asset URLs in generated HTML.
+* 改写生成 HTML 里残留的根路径静态资源地址。
+*/
+function wrapTransformHtml(siteConfig) {
+	const original = siteConfig.transformHtml;
+	siteConfig.transformHtml = async (code, id, context) => {
+		return rewriteHtmlAssetUrls(await original?.(code, id, context) ?? code, context.siteConfig.assetsBase ?? "", context.siteConfig.site.base);
+	};
+}
+/**
+* 1. config: prefix type=public built URLs with assetsBase
+* 2. configResolved: wrap buildEnd / transformHtml once (client and SSR share SiteConfig)
+* 3. transform: patch withBase, empty-shell page modules, and hashmap retry
+* 1. config：给 type=public 的构建 URL 接上 assetsBase
+* 2. configResolved：挂一次 buildEnd / transformHtml（client 与 SSR 共用同一份 SiteConfig）
+* 3. transform：补丁 withBase、空壳走完整页、hashmap 重试
+*/
+function vitepressSpaFallback() {
+	const assetsBase = { value: "" };
+	return {
+		name: "vitepress-spa-fallback",
+		apply: "build",
+		enforce: "pre",
+		config(userConfig) {
+			return { experimental: {
+				...userConfig.experimental,
+				renderBuiltUrl: createRenderBuiltUrl(assetsBase, userConfig.experimental?.renderBuiltUrl)
+			} };
+		},
+		configResolved(config) {
+			const siteConfig = config.vitepress;
+			if (!siteConfig) throw new Error("[vitepress-spa-fallback] Expected a VitePress build (config.vitepress is missing).");
+			assetsBase.value = siteConfig.assetsBase ?? "";
+			if (HOOKED in siteConfig) return;
+			Object.defineProperty(siteConfig, HOOKED, { value: true });
+			wrapBuildEnd(siteConfig);
+			wrapTransformHtml(siteConfig);
+		},
+		transform(code, id, options) {
+			return patchRuntimeModule(code, id, options, this.environment.config.consumer);
+		}
+	};
+}
+
+//#endregion
+export { vitepressSpaFallback };

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "vitepress-spa-fallback",
+  "type": "module",
+  "version": "1.0.0",
+  "description": "Vite plugin for VitePress SPA fallback.",
+  "author": "holazz",
+  "license": "MIT",
+  "homepage": "https://github.com/holazz/vitepress-spa-fallback#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/holazz/vitepress-spa-fallback"
+  },
+  "bugs": {
+    "url": "https://github.com/holazz/vitepress-spa-fallback/issues"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "files": [
+    "README.md",
+    "README.zh-CN.md",
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "peerDependencies": {
+    "vitepress": "2.0.0-alpha.20"
+  },
+  "devDependencies": {
+    "@antfu/eslint-config": "^4.19.0",
+    "@types/node": "^26.0.0",
+    "bumpp": "^10.2.3",
+    "eslint": "^9.39.4",
+    "simple-git-hooks": "^2.13.1",
+    "tsdown": "^0.16.8",
+    "typescript": "^5.8.3",
+    "vite": "8.2.2",
+    "vitepress": "2.0.0-alpha.20",
+    "vitest": "^4.1.10"
+  },
+  "simple-git-hooks": {
+    "pre-commit": "pnpm lint:fix && pnpm typecheck"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "typecheck": "tsc --noEmit",
+    "release": "bumpp"
+  }
+}