@quark-fw/plugin-react 0.1.2

package/src/i18n/config.ts

@@ -0,0 +1,112 @@
+export type I18nConfig = {
+	/** коды локалей: они же префиксы URL (/{locale}/…) и вход для Intl */
+	locales: readonly string[];
+	/** язык-фолбэк: его словарь подмешивается под все остальные */
+	defaultLocale: string;
+	/** отдавать страницы без префикса; учитывается только при одной локали */
+	urlPrefix?: boolean;
+};
+
+export const defineI18nConfig = <const T extends I18nConfig>(config: T): T =>
+	config;
+
+let invalidPrefixWarned = false;
+
+/**
+ * Единственный источник правды о том, несут ли URL префикс /{locale}.
+ * urlPrefix: false осмыслен только при одной локали — иначе многоязычный
+ * сайт молча схлопнулся бы в один язык.
+ */
+export function usesLocalePrefix(config?: I18nConfig): boolean {
+	if (!config?.locales?.length) return false;
+
+	if (config.urlPrefix === false && config.locales.length > 1) {
+		if (!invalidPrefixWarned) {
+			invalidPrefixWarned = true;
+			console.error(
+				`[i18n] urlPrefix: false требует ровно одну локаль, получено ${config.locales.length} (${config.locales.join(", ")}) — префиксы оставлены`,
+			);
+		}
+		return true;
+	}
+
+	return config.urlPrefix !== false;
+}
+
+export type ParsedLocalePath = {
+	locale: string;
+	strippedPathname: string;
+	basename: string;
+	/** путь без валидного префикса — нужен редирект */
+	redirect: boolean;
+};
+
+export function parseLocalePath(
+	pathname: string,
+	config?: I18nConfig,
+): ParsedLocalePath {
+	if (!config?.locales?.length) {
+		return {
+			locale: "",
+			strippedPathname: pathname,
+			basename: "",
+			redirect: false,
+		};
+	}
+	if (!usesLocalePrefix(config)) {
+		return {
+			locale: config.defaultLocale,
+			strippedPathname: pathname,
+			basename: "",
+			redirect: false,
+		};
+	}
+	const segment = pathname.split("/")[1];
+	if (segment && config.locales.includes(segment)) {
+		return {
+			locale: segment,
+			strippedPathname: pathname.slice(segment.length + 1) || "/",
+			basename: `/${segment}`,
+			redirect: false,
+		};
+	}
+	return {
+		locale: config.defaultLocale,
+		strippedPathname: pathname,
+		basename: "",
+		redirect: true,
+	};
+}
+
+export function buildLocalePath(locale: string, strippedPath: string): string {
+	return `/${locale}${strippedPath.startsWith("/") ? strippedPath : `/${strippedPath}`}`;
+}
+
+/** Локаль по cookie, затем по Accept-Language, иначе — дефолтная. */
+export function detectLocale(
+	cookieValue: string | undefined,
+	acceptLanguage: string | undefined,
+	config: I18nConfig,
+): string {
+	if (cookieValue && config.locales.includes(cookieValue)) return cookieValue;
+
+	if (acceptLanguage) {
+		const candidates = acceptLanguage
+			.split(",")
+			.map((part) => {
+				const [tag, ...params] = part.trim().split(";");
+				const qParam = params.find((p) => p.trim().startsWith("q="));
+				const q = qParam ? Number(qParam.trim().slice(2)) : 1;
+				return {
+					lang: tag!.trim().split("-")[0]!.toLowerCase(),
+					q: Number.isFinite(q) ? q : 0,
+				};
+			})
+			.sort((a, b) => b.q - a.q);
+		for (const { lang } of candidates) {
+			if (config.locales.includes(lang)) return lang;
+		}
+	}
+
+	return config.defaultLocale;
+}

package/src/i18n/gatherLocales.ts

@@ -0,0 +1,12 @@
+/// <reference types="vite/client" />
+
+/** словарь переводов: строки и вложенные словари */
+export type LocaleDict = { [key: string]: string | LocaleDict };
+
+export type LocaleModule = { default?: LocaleDict };
+
+// /locales/{lang}/{namespace}.ts — ровно один уровень вложенности
+const lazyLocales = import.meta.glob<LocaleModule>("/locales/*/*.ts");
+
+export const getLocaleImporter = (lang: string, namespace: string) =>
+	lazyLocales[`/locales/${lang}/${namespace}.ts`];

package/src/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>react</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/src/index.ts

@@ -0,0 +1,102 @@
+import atom from "@quark-fw/atom";
+import express from "express";
+import fs from "node:fs";
+import type { Server } from "node:http";
+import type { ViteDevServer } from "vite";
+import getRenderMiddleware from "./ssr/getRenderMiddleware.js";
+import { getVite } from "./utils/vite.js";
+import { appFrontendRoot, buildPaths } from "./utils/viteConfig.js";
+import { httpRouter, preRouter } from "@quark-fw/plugin/http.js";
+import {} from "@quark-fw/plugin-react/src/global.js";
+
+const isProd = process.env.NODE_ENV === "production";
+
+let server: Server | undefined;
+let vite: ViteDevServer | undefined;
+let unsubscribePort: (() => void) | undefined;
+
+await quark.registerPlugin({
+	name: "react",
+	extend(quark) {
+		quark.react = {
+			port: atom("react.port", Number(process.env.PORT) || 3000),
+			lang: atom("react.lang", "en"),
+			// пусто по умолчанию: без иконки ссылка не выводится, а не
+			// указывает на несуществующий файл
+			favicon: atom("react.favicon", ""),
+		};
+	},
+	async onReady(quark) {
+		const app = express();
+
+		// за обратным прокси (TLS-терминация) нужно доверять X-Forwarded-*,
+		// иначе req.secure всегда false и secure-cookie не выставляются.
+		// Включается явно: TRUST_PROXY=1 (или список адресов).
+		if (process.env.TRUST_PROXY) {
+			app.set("trust proxy", process.env.TRUST_PROXY);
+		}
+
+		// сквозные middleware (сессии, passport) — раньше всех обработчиков
+		app.use(preRouter);
+		// маршруты плагинов (например /api/trpc) — до статики и SSR
+		app.use(httpRouter);
+
+		if (isProd) {
+			const paths = buildPaths();
+			if (!fs.existsSync(paths.serverEntry)) {
+				throw new Error(
+					`[react] сборка не найдена (${paths.serverEntry}) — запусти npm run build`,
+				);
+			}
+			// хешированные ассеты кэшируются навсегда, остальное — нет
+			app.use(
+				"/assets",
+				express.static(`${paths.client}/assets`, {
+					immutable: true,
+					maxAge: "1y",
+				}),
+			);
+			app.use(express.static(paths.client, { index: false }));
+			const staticDir = `${paths.root}/static`;
+			if (fs.existsSync(staticDir)) app.use(express.static(staticDir));
+			app.use(getRenderMiddleware({}));
+		} else {
+			vite = await getVite({
+				root: appFrontendRoot(),
+				appPort: quark.react.port.value,
+			});
+			app.use(vite.middlewares);
+			app.use(getRenderMiddleware({ vite }));
+		}
+
+		const listen = (port: number) => {
+			server = app.listen(port, () => {
+				console.log(
+					`[react] ${isProd ? "production" : "dev"} http://localhost:${port}`,
+				);
+			});
+		};
+
+		listen(quark.react.port.value);
+
+		// при смене порта перезапускаем listener
+		unsubscribePort = quark.react.port.subscribe((port) => {
+			const old = server;
+			server = undefined;
+			if (old) {
+				old.close(() => listen(port));
+				old.closeAllConnections();
+			} else {
+				listen(port);
+			}
+		});
+	},
+	async onDestroy() {
+		unsubscribePort?.();
+		unsubscribePort = undefined;
+		server?.close();
+		server = undefined;
+		await vite?.close();
+		vite = undefined;
+	},
+});

package/src/seo/SeoContext.tsx

@@ -0,0 +1,94 @@
+import {
+	createContext,
+	ReactNode,
+	useContext,
+	useEffect,
+	useMemo,
+	useState,
+} from "react";
+import { useLocation } from "react-router-dom";
+import { useStore } from "@quark-fw/store";
+import { matchPath } from "react-router-dom";
+import { getMatchedRoute } from "../Router/getMatchedRoute.js";
+import type { PageMeta, ResolvedSeo } from "./createPageMeta.js";
+
+export type SeoMap = Record<string, ResolvedSeo>;
+
+export type SeoContextValue = ResolvedSeo & {
+	seoObject: SeoMap;
+	setPathnameSeo: (pathname: string, seo: ResolvedSeo) => void;
+};
+
+const SeoContext = createContext<SeoContextValue>({
+	seoObject: {},
+	setPathnameSeo: () => {},
+});
+
+export const useSeo = () => useContext(SeoContext);
+
+export function SeoProvider({
+	children,
+	seoObject: initial,
+}: {
+	children: ReactNode;
+	seoObject?: SeoMap;
+}) {
+	const [seoObject, setSeoObject] = useState<SeoMap>(initial ?? {});
+	const { pathname } = useLocation();
+	const store = useStore();
+
+	const current = seoObject[pathname];
+
+	// клиентская навигация: меты для нового пути ещё нет — резолвим её
+	// из модуля страницы (тот же resolveMeta, что и на сервере)
+	useEffect(() => {
+		if (current) return;
+		let cancelled = false;
+		void (async () => {
+			const uglyModule = getMatchedRoute(pathname);
+			if (!uglyModule) return;
+			const loaded = await uglyModule.load();
+			const meta = (loaded?.default as { meta?: PageMeta } | undefined)
+				?.meta;
+			if (!meta || cancelled) return;
+			const routeProps = matchPath(
+				{ path: uglyModule.urlPath, end: false, caseSensitive: false },
+				pathname,
+			);
+			const { resolveMeta } = await import("./createPageMeta.js");
+			const resolved = await resolveMeta(meta, {
+				store,
+				params: (routeProps?.params ?? {}) as Record<string, string>,
+			});
+			if (!cancelled) {
+				setSeoObject((prev) => ({ ...prev, [pathname]: resolved }));
+			}
+		})();
+		return () => {
+			cancelled = true;
+		};
+		// store живёт всё время жизни приложения и меняться не может, а его
+		// добавление в зависимости ничего бы не изменило
+		// eslint-disable-next-line react-hooks/exhaustive-deps
+	}, [pathname, current]);
+
+	// заголовок вкладки при клиентской навигации
+	useEffect(() => {
+		if (typeof document === "undefined") return;
+		if (current?.title) document.title = current.title;
+	}, [current?.title]);
+
+	const value = useMemo<SeoContextValue>(
+		() => ({
+			...(current ?? {}),
+			seoObject,
+			setPathnameSeo: (path, seo) =>
+				setSeoObject((prev) => ({ ...prev, [path]: seo })),
+		}),
+		[current, seoObject],
+	);
+
+	return <SeoContext.Provider value={value}>{children}</SeoContext.Provider>;
+}
+
+export default SeoContext;

package/src/seo/createPageMeta.ts

@@ -0,0 +1,68 @@
+import type { TStore } from "@quark-fw/store";
+
+// Порт createPageMeta из ugliest: страница объявляет мету, каждое поле —
+// значение ИЛИ (возможно асинхронная) функция, которая резолвится против
+// store во время SSR. Так title/description могут зависеть от данных.
+export type PageMetaContext = {
+	store: TStore;
+	params: Record<string, string>;
+};
+
+export type MetaValue<T> = T | ((ctx: PageMetaContext) => T | Promise<T>);
+
+export type PageMetaOG = {
+	title?: string;
+	description?: string;
+	image?: string;
+	type?: string;
+	siteName?: string;
+};
+
+export type PageMeta = {
+	title?: MetaValue<string>;
+	description?: MetaValue<string>;
+	/** например 'noindex, nofollow' */
+	robots?: MetaValue<string>;
+	og?: MetaValue<PageMetaOG | undefined>;
+	/** HTTP-статус ответа (например 404 для «не найдено») */
+	status?: MetaValue<number>;
+};
+
+export type ResolvedSeo = {
+	title?: string;
+	description?: string;
+	robots?: string;
+	og?: PageMetaOG;
+	status?: number;
+};
+
+export function createPageMeta(meta: PageMeta): PageMeta {
+	return meta;
+}
+
+const resolveValue = async <T>(
+	value: MetaValue<T> | undefined,
+	ctx: PageMetaContext,
+): Promise<T | undefined> => {
+	if (typeof value === "undefined") return undefined;
+	if (typeof value === "function") {
+		return (value as (c: PageMetaContext) => T | Promise<T>)(ctx);
+	}
+	return value;
+};
+
+/** Резолвит все поля меты параллельно; используется и на SSR, и на клиенте. */
+export async function resolveMeta(
+	meta: PageMeta | undefined,
+	ctx: PageMetaContext,
+): Promise<ResolvedSeo> {
+	if (!meta) return {};
+	const [title, description, robots, og, status] = await Promise.all([
+		resolveValue(meta.title, ctx),
+		resolveValue(meta.description, ctx),
+		resolveValue(meta.robots, ctx),
+		resolveValue(meta.og, ctx),
+		resolveValue(meta.status, ctx),
+	]);
+	return { title, description, robots, og, status };
+}

package/src/ssr/getRenderMiddleware.ts

@@ -0,0 +1,273 @@
+import { Manifest, 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, 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 { resolveMeta, type PageMeta } from "../seo/createPageMeta.js";
+import {
+	buildLocalePath,
+	detectLocale,
+	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";
+
+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")>;
+	};
+
+	return async function rendererMiddleware(req: Request, res: Response) {
+		try {
+			const rendererModule = await loadRenderer();
+
+			// i18n: определяем локаль по префиксу пути; голый путь при
+			// включённых префиксах уводим 302 на локаль из cookie/заголовка
+			const i18nConfig = (rendererModule as { i18nConfig?: I18nConfig })
+				.i18nConfig;
+			const urlWithoutSearch = removeSearchParamsFromUrl(req.originalUrl);
+			const { locale, strippedPathname, basename, redirect } =
+				parseLocalePath(urlWithoutSearch, i18nConfig);
+
+			if (redirect && i18nConfig) {
+				const target = detectLocale(
+					parseCookies(req.headers.cookie)["locale"],
+					req.headers["accept-language"],
+					i18nConfig,
+				);
+				const searchIndex = req.originalUrl.indexOf("?");
+				const search =
+					searchIndex === -1
+						? ""
+						: req.originalUrl.slice(searchIndex);
+				res.redirect(
+					302,
+					buildLocalePath(target, urlWithoutSearch) + search,
+				);
+				return;
+			}
+
+			const renderer = new rendererModule.Renderer({
+				url: req.originalUrl,
+				manifest,
+				locale,
+				basename,
+				strippedPathname,
+			});
+
+			const page = rendererModule.hasUglyPage(strippedPathname) as
+				UglyModule | undefined;
+
+			const requiredModules: UglyModule[] = [];
+
+			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({
+				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}]='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>`,
+							);
+						}
+					});
+				},
+			});
+
+			// мета страницы: резолвится ПЕРЕД стримом (title/description
+			// должны попасть в <head>), функции меты видят store и params
+			const pathname = strippedPathname;
+			const pageMeta = (
+				page?.module?.default as { meta?: PageMeta } | undefined
+			)?.meta;
+			const routeProps = page
+				? matchPath(
+						{
+							path: page.urlPath,
+							end: false,
+							caseSensitive: false,
+						},
+						pathname,
+					)
+				: null;
+			const seo = await resolveMeta(pageMeta, {
+				store,
+				params: (routeProps?.params ?? {}) as Record<string, string>,
+			});
+
+			res.status(seo.status ?? (page ? 200 : 404));
+
+			const data = {
+				req,
+				registerModule,
+				store,
+				trpcClient,
+				seo,
+				seoObject: { [pathname]: seo },
+				favicon: reactAtoms?.favicon?.value,
+			};
+			const head = renderer.head(data);
+			// с i18n язык берётся из закрытого списка локалей, без него —
+			// из quark.react.lang (приложение задаёт его само)
+			const htmlLang = locale || reactAtoms?.lang?.value || "en";
+			res.write(`<!doctype html><html lang="${htmlLang}">`);
+			res.write(head);
+			res.write(`<body><div id="root">`);
+			// shell записан — отпускаем отложенные записи кэша
+			htmlReadyResolve();
+
+			const stream = renderer.pipe({
+				...data,
+				options: {
+					onShellReady: () => {
+						stream.pipe(res);
+					},
+					onError: (error) => {
+						console.error(error);
+						res.end(
+							`Server Error: ${error instanceof Error ? error.message : error}`,
+						);
+					},
+					bootstrapModules,
+				},
+			});
+		} catch (e: unknown) {
+			console.error(e);
+			res.status(500).end(e instanceof Error ? e.stack : e);
+		}
+	};
+}