@quark-fw/plugin-react 0.1.8 → 0.1.10

package/package.json

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

package/src/ssr/createPreloadTagWriter.ts

@@ -0,0 +1,36 @@
+import type { Manifest } from "vite";
+import type { Response } from "express";
+import { UglyModule } from "../Router/UglyModule.js";
+
+/**
+ * Пишет в ответ preload-теги (modulepreload + css) для модулей страницы,
+ * которые регистрирует роутер по мере рендера. Каждый css — один раз.
+ */
+export function createPreloadTagWriter(manifest: Manifest, res: Response) {
+	const requiredModules: UglyModule[] = [];
+	const written: Record<string, boolean> = {};
+
+	const extractTags = (link: string): void => {
+		const chunk = manifest[link];
+		if (chunk && chunk.name !== "entry-client") {
+			res.write(
+				`<link rel="modulepreload" as="script" crossorigin href="/${chunk.file}">`,
+			);
+			(chunk.css ?? []).forEach((cssFile) => {
+				if (!written[cssFile]) {
+					written[cssFile] = true;
+					res.write(`<link rel="stylesheet" href="/${cssFile}"/>`);
+				}
+			});
+			(chunk.imports ?? []).map((childLink) => extractTags(childLink));
+		}
+	};
+
+	return function registerModule(uglyModule: UglyModule) {
+		if (!requiredModules.includes(uglyModule)) {
+			requiredModules.push(uglyModule);
+
+			extractTags(uglyModule.modulePath.substring(1));
+		}
+	};
+}

package/src/ssr/createRendererLoader.ts

@@ -0,0 +1,29 @@
+import type { ViteDevServer } from "vite";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { buildPaths } from "../utils/viteConfig.js";
+import { isProd } from "./helpers.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+type RendererModule = typeof import("../frontend/entry-server.js");
+
+/**
+ * Загрузчик SSR-бандла: в prod импортируется один раз из сборки,
+ * в dev — через vite (с HMR).
+ */
+export function createRendererLoader(vite?: ViteDevServer) {
+	let prodRenderer: Promise<RendererModule>;
+
+	return function loadRenderer(): Promise<RendererModule> {
+		if (isProd) {
+			prodRenderer ??= import(
+				pathToFileURL(buildPaths().serverEntry).href
+			) as Promise<RendererModule>;
+			return prodRenderer;
+		}
+		return vite!.ssrLoadModule(
+			path.join(__dirname, "../frontend/entry-server.js"),
+		) as Promise<RendererModule>;
+	};
+}

package/src/ssr/createRequestTrpcClient.ts

@@ -0,0 +1,23 @@
+import { createTRPCClient, httpLink } from "@trpc/client";
+import { jsonSafeFetch, type TRPCClient } from "@quark-fw/store";
+
+/**
+ * tRPC-клиент КОНКРЕТНОГО запроса: SSR ходит к собственному серверу по
+ * HTTP и пробрасывает cookie, чтобы страница рендерилась от имени
+ * залогиненного пользователя. Клиент собирается здесь, а роутер объявляет
+ * приложение — тот же шов аугментации, что и в сторе.
+ */
+export function createRequestTrpcClient(
+	port: number,
+	cookie: string | undefined,
+): TRPCClient {
+	return createTRPCClient({
+		links: [
+			httpLink({
+				url: `http://127.0.0.1:${port}/api/trpc`,
+				headers: cookie ? { cookie } : {},
+				fetch: jsonSafeFetch,
+			}),
+		],
+	}) as TRPCClient;
+}

package/src/ssr/createStreamingStore.ts

@@ -0,0 +1,47 @@
+import type { Response } from "express";
+import Store, { NOT_READY_STATE, type TRPCClient } from "@quark-fw/store";
+import serializeForScript from "../utils/serializeForScript.js";
+
+/**
+ * Store, стримящий резолв данных в ответ по мере рендера: клиентский Store
+ * гидратируется из window.cache без повторных запросов, NOT_READY_STATE
+ * будит зависшие Suspense-чтения.
+ *
+ * Мета страницы резолвится ДО записи <head>, а её tRPC-вызовы дёргают
+ * callback store — писать их сразу нельзя: заголовки ушли бы раньше
+ * res.status(), а скрипты — раньше <!doctype>. Поэтому записи кэша ждут
+ * releaseCacheWrites(), который вызывается после записи shell.
+ */
+export function createStreamingStore(trpcClient: TRPCClient, res: Response) {
+	let htmlReadyResolve!: () => void;
+	const htmlReady = new Promise<void>((resolve) => {
+		htmlReadyResolve = resolve;
+	});
+
+	const store = new Store({
+		trpcClient,
+		callback: (key, value) => {
+			const safeKey = serializeForScript(key);
+			void htmlReady.then(() => {
+				if (value === NOT_READY_STATE) {
+					res.write(
+						`<script>window.cache=window.cache||{};window.cache[${safeKey}]=${serializeForScript(NOT_READY_STATE)};</script>`,
+					);
+				} else {
+					// undefined сериализуем как null: literal undefined в
+					// window.cache читается клиентом как cache miss и
+					// приводит к повторному suspense при гидратации
+					res.write(
+						`<script>window.cache[${safeKey}]=${
+							typeof value === "undefined"
+								? "null"
+								: serializeForScript(value)
+						};window.store?.emit(${safeKey},window.cache[${safeKey}]);</script>`,
+					);
+				}
+			});
+		},
+	});
+
+	return { store, releaseCacheWrites: htmlReadyResolve };
+}

package/src/ssr/getRenderMiddleware.ts

@@ -1,17 +1,8 @@
-import { Manifest, ViteDevServer } from "vite";
+import { ViteDevServer } from "vite";
 import { Request, Response } from "express";
-import path from "node:path";
-import * as fs from "node:fs";
-import { createTRPCClient, httpLink } from "@trpc/client";
-import Store, {
-	jsonSafeFetch,
-	NOT_READY_STATE,
-	type TRPCClient,
-} from "@quark-fw/store";
-import { UglyModule } from "../Router/gatherPages.js";
-import removeSearchParamsFromUrl from "../utils/removeSearchParamsFromUrl.js";
-import serializeForScript from "../utils/serializeForScript.js";
 import { matchPath } from "react-router-dom";
+import { UglyModule } from "../Router/UglyModule.js";
+import removeSearchParamsFromUrl from "../utils/removeSearchParamsFromUrl.js";
 import { resolveMeta, type PageMeta } from "../seo/createPageMeta.js";
 import {
 	buildLocalePath,
@@ -19,63 +10,21 @@ import {
 	parseLocalePath,
 	type I18nConfig,
 } from "../i18n/config.js";
-
-/** Разбор Cookie-заголовка без внешних зависимостей. */
-const parseCookies = (header?: string): Record<string, string> =>
-	Object.fromEntries(
-		(header ?? "")
-			.split(";")
-			.map((part) => part.trim().split("="))
-			.filter((pair) => pair.length === 2)
-			.map(([k, v]) => [k!, decodeURIComponent(v!)]),
-	);
-import { fileURLToPath, pathToFileURL } from "node:url";
-import { buildPaths } from "../utils/viteConfig.js";
+import { getReactAtoms, parseCookies } from "./helpers.js";
+import { resolveClientAssets } from "./resolveClientAssets.js";
+import { createRendererLoader } from "./createRendererLoader.js";
+import { createPreloadTagWriter } from "./createPreloadTagWriter.js";
+import { createRequestTrpcClient } from "./createRequestTrpcClient.js";
+import { createStreamingStore } from "./createStreamingStore.js";
 
 export type GetRenderMiddlewareArgs = {
 	/** dev: модули грузятся через vite; в prod — из собранного бандла */
 	vite?: ViteDevServer;
 };
 
-const isProd = process.env.NODE_ENV === "production";
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-
 export default function getRenderMiddleware({ vite }: GetRenderMiddlewareArgs) {
-	const paths = buildPaths();
-
-	const manifest = (
-		isProd ? JSON.parse(fs.readFileSync(paths.manifest, "utf8")) : {}
-	) as Manifest;
-
-	const findManifestEntry = (fragment: string) =>
-		Object.entries(manifest).find(([key]) => key.includes(fragment))?.[1];
-
-	let bootstrapModules: string[];
-	if (isProd) {
-		const entry = findManifestEntry("entry-client");
-		if (!entry) {
-			throw new Error(
-				"[react] entry-client not found in build manifest — запусти сборку (npm run build)",
-			);
-		}
-		bootstrapModules = [`/${entry.file}`];
-	} else {
-		bootstrapModules = ["/entry-client.tsx"];
-	}
-
-	// в prod SSR-бандл импортируется один раз, в dev — через vite (HMR)
-	let prodRenderer: Promise<typeof import("../frontend/entry-server.js")>;
-	const loadRenderer = () => {
-		if (isProd) {
-			prodRenderer ??= import(
-				pathToFileURL(paths.serverEntry).href
-			) as Promise<typeof import("../frontend/entry-server.js")>;
-			return prodRenderer;
-		}
-		return vite!.ssrLoadModule(
-			path.join(__dirname, "../frontend/entry-server.js"),
-		) as Promise<typeof import("../frontend/entry-server.js")>;
-	};
+	const { manifest, bootstrapModules } = resolveClientAssets();
+	const loadRenderer = createRendererLoader(vite);
 
 	return async function rendererMiddleware(req: Request, res: Response) {
 		try {
@@ -118,99 +67,17 @@ export default function getRenderMiddleware({ vite }: GetRenderMiddlewareArgs) {
 			const page = rendererModule.hasUglyPage(strippedPathname) as
 				UglyModule | undefined;
 
-			const requiredModules: UglyModule[] = [];
+			const registerModule = createPreloadTagWriter(manifest, res);
 
-			const written: Record<string, boolean> = {};
-			const extractTags = (link: string): void => {
-				const _module = manifest[link];
-				if (_module && _module.name !== "entry-client") {
-					res.write(
-						`<link rel="modulepreload" as="script" crossorigin href="/${_module.file}">`,
-					);
-					(_module.css ?? []).forEach((e) => {
-						if (!written[e]) {
-							written[e] = true;
-							res.write(`<link rel="stylesheet" href="/${e}"/>`);
-						}
-					});
-					(_module.imports ?? []).map((_link) => extractTags(_link));
-				}
-			};
-			const registerModule = (_module: UglyModule) => {
-				if (!requiredModules.includes(_module)) {
-					requiredModules.push(_module);
-
-					extractTags(_module.modulePath.substring(1));
-				}
-			};
-
-			// SSR-запросы к tRPC идут в собственный сервер по HTTP (dev-режим).
-			// Атомы плагина объявлены в его аугментации Quark, но здесь берём
-			// их структурно: значения нужны как есть, до готовности плагина.
-			const reactAtoms = (
-				globalThis as {
-					quark?: {
-						react?: {
-							port?: { value?: number };
-							lang?: { value?: string };
-							favicon?: { value?: string };
-						};
-					};
-				}
-			).quark?.react;
-			const port = reactAtoms?.port?.value ?? 3000;
-			// клиент собирается здесь, а роутер объявляет приложение — тот же
-			// шов, что и в сторе
-			const trpcClient = createTRPCClient({
-				links: [
-					httpLink({
-						url: `http://127.0.0.1:${port}/api/trpc`,
-						// пробрасываем cookie запроса, чтобы SSR рендерил
-						// страницу от имени залогиненного пользователя
-						headers: req.headers.cookie
-							? { cookie: req.headers.cookie }
-							: {},
-						fetch: jsonSafeFetch,
-					}),
-				],
-			}) as TRPCClient;
-
-			// Мета страницы резолвится ДО записи <head>, а её tRPC-вызовы
-			// дёргают callback store — писать их сразу нельзя: заголовки
-			// ушли бы раньше res.status(), а скрипты — раньше <!doctype>.
-			// Поэтому все записи кэша ждут, пока shell не будет записан.
-			let htmlReadyResolve!: () => void;
-			const htmlReady = new Promise<void>((resolve) => {
-				htmlReadyResolve = resolve;
-			});
-
-			// по мере резолва данных при рендере стримим их в ответ:
-			// клиентский Store гидратируется из window.cache без повторных
-			// запросов; NOT_READY_STATE будит зависшие Suspense-чтения
-			const store = new Store({
+			const reactAtoms = getReactAtoms();
+			const trpcClient = createRequestTrpcClient(
+				reactAtoms?.port?.value ?? 3000,
+				req.headers.cookie,
+			);
+			const { store, releaseCacheWrites } = createStreamingStore(
 				trpcClient,
-				callback: (key, value) => {
-					const safeKey = serializeForScript(key);
-					void htmlReady.then(() => {
-						if (value === NOT_READY_STATE) {
-							res.write(
-								`<script>window.cache=window.cache||{};window.cache[${safeKey}]=${serializeForScript(NOT_READY_STATE)};</script>`,
-							);
-						} else {
-							// undefined сериализуем как null: literal undefined в
-							// window.cache читается клиентом как cache miss и
-							// приводит к повторному suspense при гидратации
-							res.write(
-								`<script>window.cache[${safeKey}]=${
-									typeof value === "undefined"
-										? "null"
-										: serializeForScript(value)
-								};window.store?.emit(${safeKey},window.cache[${safeKey}]);</script>`,
-							);
-						}
-					});
-				},
-			});
+				res,
+			);
 
 			// мета страницы: резолвится ПЕРЕД стримом (title/description
 			// должны попасть в <head>), функции меты видят store и params
@@ -252,7 +119,7 @@ export default function getRenderMiddleware({ vite }: GetRenderMiddlewareArgs) {
 			res.write(head);
 			res.write(`<body><div id="root">`);
 			// shell записан — отпускаем отложенные записи кэша
-			htmlReadyResolve();
+			releaseCacheWrites();
 
 			const stream = renderer.pipe({
 				...data,

package/src/ssr/helpers.ts

@@ -0,0 +1,26 @@
+// Хелперы SSR-мидлвары.
+
+export const isProd = process.env.NODE_ENV === "production";
+
+/** Разбор Cookie-заголовка без внешних зависимостей. */
+export const parseCookies = (header?: string): Record<string, string> =>
+	Object.fromEntries(
+		(header ?? "")
+			.split(";")
+			.map((part) => part.trim().split("="))
+			.filter((pair) => pair.length === 2)
+			.map(([k, v]) => [k!, decodeURIComponent(v!)]),
+	);
+
+/**
+ * Атомы react-плагина. Объявлены в его аугментации Quark, но читаются
+ * структурно: значения нужны как есть, до готовности плагина.
+ */
+export type ReactAtoms = {
+	port?: { value?: number };
+	lang?: { value?: string };
+	favicon?: { value?: string };
+};
+
+export const getReactAtoms = (): ReactAtoms | undefined =>
+	(globalThis as { quark?: { react?: ReactAtoms } }).quark?.react;

package/src/ssr/resolveClientAssets.ts

@@ -0,0 +1,31 @@
+import type { Manifest } from "vite";
+import * as fs from "node:fs";
+import { buildPaths } from "../utils/viteConfig.js";
+import { isProd } from "./helpers.js";
+
+/**
+ * Клиентские ассеты рендера: манифест сборки и entry-модули для
+ * bootstrapModules. В dev манифеста нет — vite отдаёт исходник напрямую.
+ */
+export function resolveClientAssets(): {
+	manifest: Manifest;
+	bootstrapModules: string[];
+} {
+	const paths = buildPaths();
+
+	const manifest = (
+		isProd ? JSON.parse(fs.readFileSync(paths.manifest, "utf8")) : {}
+	) as Manifest;
+
+	if (!isProd) return { manifest, bootstrapModules: ["/entry-client.tsx"] };
+
+	const entry = Object.entries(manifest).find(([key]) =>
+		key.includes("entry-client"),
+	)?.[1];
+	if (!entry) {
+		throw new Error(
+			"[react] entry-client not found in build manifest — запусти сборку (npm run build)",
+		);
+	}
+	return { manifest, bootstrapModules: [`/${entry.file}`] };
+}

package/src/utils/vite.ts

@@ -20,8 +20,15 @@ export async function getVite({
 					strictPort: true,
 					middlewareMode: true,
 					// у каждого приложения свой HMR-сокет: иначе вторая
-					// запущенная апка ловит "Port 24678 is already in use"
-					hmr: { port: appPort + 20000 },
+					// запущенная апка ловит "Port 24678 is already in use".
+					// Высокие appPort заворачиваются в валидный диапазон,
+					// иначе ERR_SOCKET_BAD_PORT (порт > 65535)
+					hmr: {
+						port:
+							appPort + 20000 <= 65535
+								? appPort + 20000
+								: 1024 + ((appPort + 20000) % 64512),
+					},
 				},
 			}),
 		);