@quark-fw/plugin-react 0.1.14 → 0.1.16

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@quark-fw/plugin-react",
-	"version": "0.1.14",
+	"version": "0.1.16",
 	"main": "src/index.ts",
 	"types": "src/index.ts",
 	"type": "module",
@@ -22,8 +22,8 @@
 		"access": "public"
 	},
 	"dependencies": {
-		"@quark-fw/atom": "0.1.14",
-		"@quark-fw/plugin": "0.1.14",
+		"@quark-fw/atom": "0.1.16",
+		"@quark-fw/plugin": "0.1.16",
 		"@trpc/client": "^11.0.0",
 		"@types/react-dom": "^19.2.3",
 		"express": "^5.2.1",
@@ -36,8 +36,8 @@
 		"@mantine/dates": "^9.0.0",
 		"@mantine/modals": "^9.0.0",
 		"@mantine/notifications": "^9.0.0",
-		"@quark-fw/core": "0.1.14",
-		"@quark-fw/store": "0.1.14",
+		"@quark-fw/core": "0.1.16",
+		"@quark-fw/store": "0.1.16",
 		"@vitejs/plugin-react": "^5.1.0",
 		"react": "^19.2.4",
 		"react-dom": "^19.2.4",

package/src/frontend/App.tsx

@@ -77,7 +77,10 @@ export default function App({
 				<ModalsProvider>
 					<TRPCContext value={trpcClient}>
 						<StoreContext value={store}>
-							<SeoProvider seoObject={seoObject}>
+							<SeoProvider
+								seoObject={seoObject}
+								locale={locale || i18nConfig?.defaultLocale}
+							>
 								{i18nConfig ? (
 									<I18nProvider
 										locale={

package/src/frontend/HTML/index.tsx

@@ -5,6 +5,8 @@ import removeSearchParamsFromUrl from "../../utils/removeSearchParamsFromUrl.js"
 import serializeForScript from "../../utils/serializeForScript.js";
 import type { ResolvedSeo } from "../../seo/createPageMeta.js";
 
+export type HTMLAlternate = { hreflang: string; href: string };
+
 export type HTMLProps = {
 	children?: ReactNode;
 	colorScheme: "dark" | "light" | undefined;
@@ -15,6 +17,10 @@ export type HTMLProps = {
 	seo?: ResolvedSeo;
 	/** иконка вкладки; приложение задаёт её атомом quark.react.favicon */
 	favicon?: string;
+	/** абсолютный origin (https://host): делает canonical/og:url абсолютными */
+	origin?: string;
+	/** hreflang-кластер страницы (приложения с префиксами локалей) */
+	alternates?: HTMLAlternate[];
 };
 
 function HTML({
@@ -24,14 +30,29 @@ function HTML({
 	seoPathname,
 	seo,
 	favicon,
+	origin,
+	alternates,
 }: HTMLProps) {
-	const canonical = removeSearchParamsFromUrl(pathname!);
+	const path = removeSearchParamsFromUrl(pathname!);
+	// без origin остаётся относительный URL — как было до появления поля
+	const canonical = origin ? origin + path : path;
+	// относительная картинка og:image без origin бесполезна для соцсетей
+	const abs = (url?: string) =>
+		url && url.startsWith("/") && origin ? origin + url : url;
 	const og = seo?.og;
 	return (
 		<>
 			<head>
 				<title>{seo?.title ?? "App"}</title>
 				<link rel="canonical" href={canonical} />
+				{alternates?.map((alt) => (
+					<link
+						rel="alternate"
+						hrefLang={alt.hreflang}
+						href={alt.href}
+						key={alt.hreflang}
+					/>
+				))}
 				{favicon ? <link rel="icon" href={favicon} /> : null}
 				{seo?.description ? (
 					<meta name="description" content={seo.description} />
@@ -59,7 +80,7 @@ function HTML({
 							/>
 						) : null}
 						{og?.image ? (
-							<meta property="og:image" content={og.image} />
+							<meta property="og:image" content={abs(og.image)} />
 						) : null}
 						{og?.siteName ? (
 							<meta
@@ -67,8 +88,20 @@ function HTML({
 								content={og.siteName}
 							/>
 						) : null}
+						{og?.locale ? (
+							<meta property="og:locale" content={og.locale} />
+						) : null}
 					</>
 				) : null}
+				{seo?.jsonLD?.map((node, index) => (
+					<script
+						key={index}
+						type="application/ld+json"
+						dangerouslySetInnerHTML={{
+							__html: serializeForScript(node),
+						}}
+					/>
+				))}
 				{/* мета для клиентской навигации (SeoProvider) */}
 				<script
 					dangerouslySetInnerHTML={{
@@ -76,7 +109,7 @@ function HTML({
 						// (basename роутера уже срезан), иначе SeoProvider
 						// промахнётся и перезапросит мету заново
 						__html: `window.seo=${serializeForScript({
-							[seoPathname ?? canonical]: seo ?? {},
+							[seoPathname ?? path]: seo ?? {},
 						})}`,
 					}}
 				/>

package/src/frontend/entry-server.tsx

@@ -12,7 +12,7 @@ import {
 	UglyModule,
 	ViteModulesEager,
 } from "../Router/gatherPages.js";
-import HTML from "./HTML/index.js";
+import HTML, { type HTMLAlternate } from "./HTML/index.js";
 import App from "./App.js";
 import type { ResolvedSeo } from "../seo/createPageMeta.js";
 import type { I18nConfig } from "../i18n/config.js";
@@ -51,6 +51,10 @@ export interface RendererPipeParams {
 	seoObject?: Record<string, ResolvedSeo>;
 	/** иконка вкладки из атома приложения */
 	favicon?: string;
+	/** абсолютный origin запроса (см. getRequestOrigin) */
+	origin?: string;
+	/** hreflang-кластер страницы */
+	alternates?: HTMLAlternate[];
 }
 
 export const hasUglyPage = (url: string) => getMatchedRoute(url, uglyPages);
@@ -87,6 +91,8 @@ export class Renderer {
 		req,
 		seo,
 		favicon,
+		origin,
+		alternates,
 	}: Omit<RendererPipeParams, "options">) {
 		return ReactDOMServer.renderToString(
 			<HTML
@@ -96,6 +102,8 @@ export class Renderer {
 				manifest={this.manifest}
 				seo={seo}
 				favicon={favicon}
+				origin={origin}
+				alternates={alternates}
 			/>,
 		);
 	}

package/src/seo/SeoProvider.tsx

@@ -9,9 +9,12 @@ import SeoContext, { type SeoContextValue, type SeoMap } from "./SeoContext.js";
 export function SeoProvider({
 	children,
 	seoObject: initial,
+	locale,
 }: {
 	children: ReactNode;
 	seoObject?: SeoMap;
+	/** активная локаль — её видят функции меты при клиентской навигации */
+	locale?: string;
 }) {
 	const [seoObject, setSeoObject] = useState<SeoMap>(initial ?? {});
 	const { pathname } = useLocation();
@@ -39,6 +42,11 @@ export function SeoProvider({
 			const resolved = await resolveMeta(meta, {
 				store,
 				params: (routeProps?.params ?? {}) as Record<string, string>,
+				locale,
+				origin:
+					typeof window === "undefined"
+						? undefined
+						: window.location.origin,
 			});
 			if (!cancelled) {
 				setSeoObject((prev) => ({ ...prev, [pathname]: resolved }));
@@ -48,7 +56,8 @@ export function SeoProvider({
 			cancelled = true;
 		};
 		// store живёт всё время жизни приложения и меняться не может, а его
-		// добавление в зависимости ничего бы не изменило
+		// добавление в зависимости ничего бы не изменило; locale меняется
+		// только полной перезагрузкой (setLocale)
 		// eslint-disable-next-line react-hooks/exhaustive-deps
 	}, [pathname, current]);
 

package/src/seo/createPageMeta.test.ts

@@ -0,0 +1,24 @@
+import { expect, test } from "vitest";
+import { resolveMeta } from "./createPageMeta.js";
+
+test("resolveMeta передаёт locale и origin в функции меты и резолвит jsonLD", async () => {
+	const ctx = {
+		store: {} as never,
+		params: { city: "tbilisi" },
+		locale: "ru",
+		origin: "https://bina.rent",
+	};
+	const seo = await resolveMeta(
+		{
+			title: ({ locale, params }) => `${locale}:${params["city"]}`,
+			jsonLD: ({ origin }) => [{ "@type": "WebSite", url: `${origin}/` }],
+			og: { locale: "ru_RU" },
+		},
+		ctx,
+	);
+	expect(seo.title).toBe("ru:tbilisi");
+	expect(seo.jsonLD).toEqual([
+		{ "@type": "WebSite", url: "https://bina.rent/" },
+	]);
+	expect(seo.og?.locale).toBe("ru_RU");
+});

package/src/seo/createPageMeta.ts

@@ -6,6 +6,14 @@ import type { TStore } from "@quark-fw/store";
 export type PageMetaContext = {
 	store: TStore;
 	params: Record<string, string>;
+	/** активная локаль (только у приложений с /i18n.ts) */
+	locale?: string;
+	/**
+	 * Абсолютный origin запроса (https://host) — для абсолютных URL в
+	 * JSON-LD и og-тегах. На SSR берётся из PUBLIC_ORIGIN или заголовков,
+	 * на клиенте — из window.location.
+	 */
+	origin?: string;
 };
 
 export type MetaValue<T> = T | ((ctx: PageMetaContext) => T | Promise<T>);
@@ -16,14 +24,21 @@ export type PageMetaOG = {
 	image?: string;
 	type?: string;
 	siteName?: string;
+	/** og:locale, например ru_RU */
+	locale?: string;
 };
 
+/** узел JSON-LD; форма задаётся schema.org, здесь — только объект */
+export type JsonLd = Record<string, unknown>;
+
 export type PageMeta = {
 	title?: MetaValue<string>;
 	description?: MetaValue<string>;
 	/** например 'noindex, nofollow' */
 	robots?: MetaValue<string>;
 	og?: MetaValue<PageMetaOG | undefined>;
+	/** структурированные данные: по <script type="application/ld+json"> на узел */
+	jsonLD?: MetaValue<JsonLd[] | undefined>;
 	/** HTTP-статус ответа (например 404 для «не найдено») */
 	status?: MetaValue<number>;
 };
@@ -33,6 +48,7 @@ export type ResolvedSeo = {
 	description?: string;
 	robots?: string;
 	og?: PageMetaOG;
+	jsonLD?: JsonLd[];
 	status?: number;
 };
 
@@ -57,12 +73,13 @@ export async function resolveMeta(
 	ctx: PageMetaContext,
 ): Promise<ResolvedSeo> {
 	if (!meta) return {};
-	const [title, description, robots, og, status] = await Promise.all([
+	const [title, description, robots, og, jsonLD, status] = await Promise.all([
 		resolveValue(meta.title, ctx),
 		resolveValue(meta.description, ctx),
 		resolveValue(meta.robots, ctx),
 		resolveValue(meta.og, ctx),
+		resolveValue(meta.jsonLD, ctx),
 		resolveValue(meta.status, ctx),
 	]);
-	return { title, description, robots, og, status };
+	return { title, description, robots, og, jsonLD, status };
 }

package/src/ssr/getRenderMiddleware.ts

@@ -8,9 +8,15 @@ import {
 	buildLocalePath,
 	detectLocale,
 	parseLocalePath,
+	usesLocalePrefix,
 	type I18nConfig,
 } from "../i18n/config.js";
-import { getReactAtoms, parseCookies } from "./helpers.js";
+import {
+	getReactAtoms,
+	getRequestOrigin,
+	parseCookies,
+	serverErrorBody,
+} from "./helpers.js";
 import { resolveClientAssets } from "./resolveClientAssets.js";
 import { createRendererLoader } from "./createRendererLoader.js";
 import { createPreloadTagWriter } from "./createPreloadTagWriter.js";
@@ -80,8 +86,10 @@ export default function getRenderMiddleware({ vite }: GetRenderMiddlewareArgs) {
 			);
 
 			// мета страницы: резолвится ПЕРЕД стримом (title/description
-			// должны попасть в <head>), функции меты видят store и params
+			// должны попасть в <head>), функции меты видят store, params,
+			// локаль и origin
 			const pathname = strippedPathname;
+			const origin = getRequestOrigin(req);
 			const pageMeta = (
 				page?.module?.default as { meta?: PageMeta } | undefined
 			)?.meta;
@@ -98,10 +106,32 @@ export default function getRenderMiddleware({ vite }: GetRenderMiddlewareArgs) {
 			const seo = await resolveMeta(pageMeta, {
 				store,
 				params: (routeProps?.params ?? {}) as Record<string, string>,
+				locale: locale || undefined,
+				origin,
 			});
 
 			res.status(seo.status ?? (page ? 200 : 404));
 
+			// hreflang-кластер: каждая локаль + x-default на дефолтную
+			const alternates =
+				i18nConfig && usesLocalePrefix(i18nConfig)
+					? [
+							...i18nConfig.locales.map((l) => ({
+								hreflang: l,
+								href: origin + buildLocalePath(l, pathname),
+							})),
+							{
+								hreflang: "x-default",
+								href:
+									origin +
+									buildLocalePath(
+										i18nConfig.defaultLocale,
+										pathname,
+									),
+							},
+						]
+					: undefined;
+
 			const data = {
 				req,
 				registerModule,
@@ -110,8 +140,15 @@ export default function getRenderMiddleware({ vite }: GetRenderMiddlewareArgs) {
 				seo,
 				seoObject: { [pathname]: seo },
 				favicon: reactAtoms?.favicon?.value,
+				origin,
+				alternates,
 			};
-			const head = renderer.head(data);
+			// INJECT_HTML — разметка оператора (счётчики, verification), не
+			// пользовательский ввод; вставляется в конец <head> как есть
+			const injectHtml = process.env.INJECT_HTML ?? "";
+			const head = renderer
+				.head(data)
+				.replace(/<\/head>$/, `${injectHtml}</head>`);
 			// с i18n язык берётся из закрытого списка локалей, без него —
 			// из quark.react.lang (приложение задаёт его само)
 			const htmlLang = locale || reactAtoms?.lang?.value || "en";
@@ -129,16 +166,14 @@ export default function getRenderMiddleware({ vite }: GetRenderMiddlewareArgs) {
 					},
 					onError: (error) => {
 						console.error(error);
-						res.end(
-							`Server Error: ${error instanceof Error ? error.message : error}`,
-						);
+						res.end(serverErrorBody(error, "message"));
 					},
 					bootstrapModules,
 				},
 			});
 		} catch (e: unknown) {
 			console.error(e);
-			res.status(500).end(e instanceof Error ? e.stack : e);
+			res.status(500).end(serverErrorBody(e, "stack"));
 		}
 	};
 }

package/src/ssr/helpers.test.ts

@@ -0,0 +1,47 @@
+import { afterEach, expect, test, vi } from "vitest";
+
+afterEach(() => {
+	vi.unstubAllEnvs();
+	vi.resetModules();
+});
+
+// isProd читается при импорте, поэтому модуль грузим после stubEnv
+const load = () => import("./helpers.js");
+
+test("parseCookies не падает на кривой %-последовательности", async () => {
+	const { parseCookies } = await load();
+	expect(parseCookies("a=%E0%A4%A; b=%D0%BF")).toEqual({
+		a: "%E0%A4%A",
+		b: "п",
+	});
+});
+
+test("serverErrorBody в проде без подробностей", async () => {
+	vi.stubEnv("NODE_ENV", "production");
+	const { serverErrorBody } = await load();
+	expect(serverErrorBody(new Error("db password=x"), "stack")).toBe(
+		"Server Error",
+	);
+});
+
+test("serverErrorBody в dev — со стеком", async () => {
+	vi.stubEnv("NODE_ENV", "development");
+	const { serverErrorBody } = await load();
+	const body = serverErrorBody(new Error("boom"), "stack");
+	expect(body).toContain("boom");
+	expect(body).toContain("helpers.test.ts");
+});
+
+test("getRequestOrigin: PUBLIC_ORIGIN главнее заголовков, хвостовой / срезается", async () => {
+	vi.stubEnv("PUBLIC_ORIGIN", "https://bina.rent/");
+	const { getRequestOrigin } = await load();
+	const req = { protocol: "http", get: () => "internal:3000" };
+	expect(getRequestOrigin(req as never)).toBe("https://bina.rent");
+});
+
+test("getRequestOrigin: без PUBLIC_ORIGIN — протокол и host запроса", async () => {
+	vi.stubEnv("PUBLIC_ORIGIN", "");
+	const { getRequestOrigin } = await load();
+	const req = { protocol: "https", get: () => "tt.drus.dev" };
+	expect(getRequestOrigin(req as never)).toBe("https://tt.drus.dev");
+});

package/src/ssr/helpers.ts

@@ -1,4 +1,5 @@
 // Хелперы SSR-мидлвары.
+import type { Request } from "express";
 
 export const isProd = process.env.NODE_ENV === "production";
 
@@ -9,9 +10,32 @@ export const parseCookies = (header?: string): Record<string, string> =>
 			.split(";")
 			.map((part) => part.trim().split("="))
 			.filter((pair) => pair.length === 2)
-			.map(([k, v]) => [k!, decodeURIComponent(v!)]),
+			.map(([k, v]) => [k!, safeDecode(v!)]),
 	);
 
+// кривая %-последовательность в чужой cookie не должна ронять рендер
+// всей страницы в 500 — оставляем значение как есть
+const safeDecode = (value: string) => {
+	try {
+		return decodeURIComponent(value);
+	} catch {
+		return value;
+	}
+};
+
+/**
+ * Тело ответа при ошибке рендера. В проде — без подробностей: стек и
+ * сообщение раскрывают пути, версии и внутренности приложения.
+ */
+export const serverErrorBody = (
+	error: unknown,
+	detail: "message" | "stack",
+): string => {
+	if (isProd) return "Server Error";
+	const text = error instanceof Error ? error[detail] : undefined;
+	return `Server Error: ${text ?? String(error)}`;
+};
+
 /**
  * Атомы react-плагина. Объявлены в его аугментации Quark, но читаются
  * структурно: значения нужны как есть, до готовности плагина.
@@ -24,3 +48,17 @@ export type ReactAtoms = {
 
 export const getReactAtoms = (): ReactAtoms | undefined =>
 	(globalThis as { quark?: { react?: ReactAtoms } }).quark?.react;
+
+/**
+ * Абсолютный origin запроса для canonical/hreflang/JSON-LD.
+ *
+ * PUBLIC_ORIGIN главнее заголовков: за прокси Host может быть внутренним, а
+ * канонический адрес сайта оператор знает точно. Без него — протокол и host
+ * из запроса (req.protocol учитывает X-Forwarded-Proto при TRUST_PROXY).
+ */
+export const getRequestOrigin = (req: Request): string => {
+	const configured = process.env.PUBLIC_ORIGIN?.trim();
+	if (configured) return configured.replace(/\/$/, "");
+	const host = req.get("host");
+	return host ? `${req.protocol}://${host}` : "";
+};

package/src/utils/createViteConfig.ts

@@ -1,109 +1,109 @@
-import type { InlineConfig, PluginOption } from "vite";
-import react from "@vitejs/plugin-react";
-import tsconfigPaths from "vite-tsconfig-paths";
-import svgr from "vite-plugin-svgr";
-import { patchCssModules } from "vite-css-modules";
-import fs from "node:fs";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import { loadModulesFromExternalFolderPlugin } from "./plugins.js";
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-
-/**
- * Пакеты @quark/* в приложении — это симлинки на ИСХОДНИКИ соседних
- * workspace-пакетов. Если позволить vite их пре-бандлить, он кэширует
- * результат в node_modules/.vite и продолжает отдавать старую версию даже
- * после правок в пакете (правка видна только после ручной очистки кэша).
- * Поэтому исключаем их из оптимизации — тогда HMR работает как для
- * обычных файлов приложения.
- */
-const workspacePackages = (cwd: string): string[] => {
-	try {
-		const pkg = JSON.parse(
-			fs.readFileSync(path.join(cwd, "package.json"), "utf8"),
-		) as Record<string, Record<string, string> | undefined>;
-		return Object.keys({
-			...(pkg.dependencies ?? {}),
-			...(pkg.devDependencies ?? {}),
-		}).filter(
-			(name) =>
-				name.startsWith("@quark/") || name.startsWith("@quark-fw/"),
-		);
-	} catch {
-		return [];
-	}
-};
-
-/** Плагин поставлен из npm (лежит внутри node_modules), а не симлинкован из монорепы. */
-const installedFromRegistry = fs
-	.realpathSync(__dirname)
-	.replace(/\\/g, "/")
-	.includes("/node_modules/");
-
-/**
- * Реестр страниц (`import.meta.glob` по /Pages) лежит внутри самого плагина, то
- * есть в node_modules приложения. Такие модули vite отдаёт с
- * `Cache-Control: max-age=31536000, immutable`, считая их неизменяемыми, и
- * версионирует хэшем зависимостей — а он не меняется от появления новой
- * страницы в приложении. Браузер продолжает исполнять старый реестр: сервер
- * страницу отрисовал, а клиентский роутер её маршрута не знает и после
- * гидратации показывает 404 (лечилось только Ctrl+F5). Содержимое этого модуля
- * зависит от файлов приложения, поэтому кэшировать его нельзя.
- */
-const pageRegistryNoCachePlugin = (): PluginOption => ({
-	name: "quark:page-registry-no-cache",
-	apply: "serve",
-	configureServer(server) {
-		server.middlewares.use((req, res, next) => {
-			if (req.url?.includes("/Router/gatherPages.")) {
-				const setHeader = res.setHeader.bind(res);
-				res.setHeader = (name, value) =>
-					/^cache-control$/i.test(name)
-						? setHeader(name, "no-cache")
-						: setHeader(name, value);
-			}
-			next();
-		});
-	},
-});
-
-/** Единая конфигурация vite для dev-сервера и для сборки. */
-export function createViteConfig(overrides?: InlineConfig): InlineConfig {
-	return {
-		plugins: [
-			patchCssModules(),
-			svgr({ include: "**/*.svg" }),
-			react(),
-			tsconfigPaths(),
-			loadModulesFromExternalFolderPlugin(),
-			pageRegistryNoCachePlugin(),
-		],
-		// Установленный из реестра плагин лежит в node_modules, куда
-		// @vitejs/plugin-react не заглядывает (у него exclude /node_modules/).
-		// Без явного automatic-рантайма его собственный JSX собирается в
-		// React.createElement и падает с "React is not defined".
-		esbuild: { jsx: "automatic", jsxImportSource: "react" },
-		optimizeDeps: {
-			exclude: workspacePackages(process.cwd()),
-			// Плагин исключён из оптимизации, поэтому vite не сканирует его
-			// импорты: установленный из реестра, он тянет react-router и mantine
-			// сырыми, и CJS-пакеты внутри них (cookie) падают на named-импортах.
-			// В монорепо, наоборот, форсировать пре-бандл нельзя — рядом с
-			// симлинкованными исходниками появилась бы вторая копия React.
-			include: installedFromRegistry
-				? [
-						"react",
-						"react-dom",
-						"react-dom/client",
-						"react-router-dom",
-						"@mantine/core",
-						"@mantine/dates",
-						"@mantine/modals",
-						"@mantine/notifications",
-					]
-				: [],
-		},
-		...overrides,
-	};
-}
+import type { InlineConfig, PluginOption } from "vite";
+import react from "@vitejs/plugin-react";
+import tsconfigPaths from "vite-tsconfig-paths";
+import svgr from "vite-plugin-svgr";
+import { patchCssModules } from "vite-css-modules";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadModulesFromExternalFolderPlugin } from "./plugins.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Пакеты @quark/* в приложении — это симлинки на ИСХОДНИКИ соседних
+ * workspace-пакетов. Если позволить vite их пре-бандлить, он кэширует
+ * результат в node_modules/.vite и продолжает отдавать старую версию даже
+ * после правок в пакете (правка видна только после ручной очистки кэша).
+ * Поэтому исключаем их из оптимизации — тогда HMR работает как для
+ * обычных файлов приложения.
+ */
+const workspacePackages = (cwd: string): string[] => {
+	try {
+		const pkg = JSON.parse(
+			fs.readFileSync(path.join(cwd, "package.json"), "utf8"),
+		) as Record<string, Record<string, string> | undefined>;
+		return Object.keys({
+			...(pkg.dependencies ?? {}),
+			...(pkg.devDependencies ?? {}),
+		}).filter(
+			(name) =>
+				name.startsWith("@quark/") || name.startsWith("@quark-fw/"),
+		);
+	} catch {
+		return [];
+	}
+};
+
+/** Плагин поставлен из npm (лежит внутри node_modules), а не симлинкован из монорепы. */
+const installedFromRegistry = fs
+	.realpathSync(__dirname)
+	.replace(/\\/g, "/")
+	.includes("/node_modules/");
+
+/**
+ * Реестр страниц (`import.meta.glob` по /Pages) лежит внутри самого плагина, то
+ * есть в node_modules приложения. Такие модули vite отдаёт с
+ * `Cache-Control: max-age=31536000, immutable`, считая их неизменяемыми, и
+ * версионирует хэшем зависимостей — а он не меняется от появления новой
+ * страницы в приложении. Браузер продолжает исполнять старый реестр: сервер
+ * страницу отрисовал, а клиентский роутер её маршрута не знает и после
+ * гидратации показывает 404 (лечилось только Ctrl+F5). Содержимое этого модуля
+ * зависит от файлов приложения, поэтому кэшировать его нельзя.
+ */
+const pageRegistryNoCachePlugin = (): PluginOption => ({
+	name: "quark:page-registry-no-cache",
+	apply: "serve",
+	configureServer(server) {
+		server.middlewares.use((req, res, next) => {
+			if (req.url?.includes("/Router/gatherPages.")) {
+				const setHeader = res.setHeader.bind(res);
+				res.setHeader = (name, value) =>
+					/^cache-control$/i.test(name)
+						? setHeader(name, "no-cache")
+						: setHeader(name, value);
+			}
+			next();
+		});
+	},
+});
+
+/** Единая конфигурация vite для dev-сервера и для сборки. */
+export function createViteConfig(overrides?: InlineConfig): InlineConfig {
+	return {
+		plugins: [
+			patchCssModules(),
+			svgr({ include: "**/*.svg" }),
+			react(),
+			tsconfigPaths(),
+			loadModulesFromExternalFolderPlugin(),
+			pageRegistryNoCachePlugin(),
+		],
+		// Установленный из реестра плагин лежит в node_modules, куда
+		// @vitejs/plugin-react не заглядывает (у него exclude /node_modules/).
+		// Без явного automatic-рантайма его собственный JSX собирается в
+		// React.createElement и падает с "React is not defined".
+		esbuild: { jsx: "automatic", jsxImportSource: "react" },
+		optimizeDeps: {
+			exclude: workspacePackages(process.cwd()),
+			// Плагин исключён из оптимизации, поэтому vite не сканирует его
+			// импорты: установленный из реестра, он тянет react-router и mantine
+			// сырыми, и CJS-пакеты внутри них (cookie) падают на named-импортах.
+			// В монорепо, наоборот, форсировать пре-бандл нельзя — рядом с
+			// симлинкованными исходниками появилась бы вторая копия React.
+			include: installedFromRegistry
+				? [
+						"react",
+						"react-dom",
+						"react-dom/client",
+						"react-router-dom",
+						"@mantine/core",
+						"@mantine/dates",
+						"@mantine/modals",
+						"@mantine/notifications",
+					]
+				: [],
+		},
+		...overrides,
+	};
+}