vitepress-plugin-cross-site-router

Исправляет навигацию и prefetch между несколькими независимо развёрнутыми экземплярами VitePress на одном origin.

Проблема

При хостинге нескольких VitePress-сайтов на одном домене с разными base-путями (например /alt-server/, /alt-workstation/) возникают две проблемы:

1. Ошибка SPA-навигации — VitePress перехватывает все клики по ссылкам одного origin и пытается выполнить SPA-переход, не находит чанки соседнего сайта и ломается.
2. Лишние prefetch-запросы — prefetcher VitePress пытается предзагрузить страницы соседних сайтов, получая 404.

Решение

Плагин подменяет логику router'а и prefetch'а:

1. Перехватывает router.onBeforeRouteChange — если href не принадлежит текущему base, выполняет location.href (полный переход).
2. Оборачивает window.IntersectionObserver до того, как VitePress создаст prefetch-observer — ссылки на соседние сайты в очередь prefetch не попадают.

Установка

npm install @ampernic/vitepress-plugin-cross-site-router

Использование

Плагин состоит из двух частей: Vite-плагин (опционален, зарезервирован для будущего) и клиентский рантайм.

VitePress config

import { CrossSiteRouterPlugin } from '@ampernic/vitepress-plugin-cross-site-router'

export default defineConfig({
  vite: {
    plugins: [CrossSiteRouterPlugin()],
  },
})

Theme enhanceApp

import {
  installCrossSiteRouter,
  suppressCrossSitePrefetch,
} from '@ampernic/vitepress-plugin-cross-site-router/client'

export default {
  enhanceApp({ router, siteData }) {
    installCrossSiteRouter(router, siteData)
    suppressCrossSitePrefetch(siteData)
  },
}

API

installCrossSiteRouter(router, siteData)

Устанавливает хук router.onBeforeRouteChange. Если целевой href не начинается с siteData.base или отсутствует в __VP_HASH_MAP__ (prod), выполняет location.href вместо SPA-перехода.

suppressCrossSitePrefetch(siteData)

Подменяет window.IntersectionObserver так, чтобы prefetch-observer VitePress никогда не добавлял в очередь ссылки, ведущие за пределы siteData.base.

isCrossSiteHref(href, base)

Утилита для проверки, является ли href межсайтовым относительно данного base.

CrossSiteRouterPlugin(options?)

Vite-плагин. Сейчас служит точкой входа для будущей build-time интеграции.

Опция	Тип	Описание
isCrossSite	(href, base) => boolean | undefined	Кастомный предикат определения межсайтовых ссылок