@ivlev-dev/silent-server
v0.12.0
Published
Server-side rendering for Silent Framework without DOM dependencies
Maintainers
Readme
@ivlev-dev/silent-server
SSR для Silent Framework без jsdom и linkedom: собственный мини-DOM, асинхронные ViewModel и гидрация серверной разметки.
Возможности
renderToStringвозвращает{ html, head }: разметку приложения и метаданные для<head>.- Собственный мини-DOM: парсер шаблонов компилятора, документ,
TreeWalkerи сериализатор без внешних DOM-зависимостей. - Асинхронные ViewModel,
Suspenseиlazyдожидаются до сериализации — в результат попадает итоговое содержимое. <title>из любого компонента выносится из дерева вRenderResult.head, как в React 19.- Серверные якоря и маркеры
data-silent-a-*сохраняются для адоптации узлов приhydrate. - Вызовы сериализуются внутренней очередью, а DOM-глобалы живут только на время рендера.
Установка
pnpm add @ivlev-dev/silent-servernpm install @ivlev-dev/silent-serveryarn add @ivlev-dev/silent-serverПакет поставляется как ESM с объявлениями типов и требует Node.js 22 или новее.
Быстрый старт
import { createServer } from "node:http";
import { renderToString } from "@ivlev-dev/silent-server";
import { App } from "./app.js";
createServer(async (request, response) => {
try {
const { html, head } = await renderToString(App, {
props: { title: "Silent Framework" },
});
const page = `<!doctype html>
<html lang="ru">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
${head}
</head>
<body>
<div id="app">${html}</div>
<script type="module" src="/client.js"></script>
</body>
</html>`;
response.setHeader("content-type", "text/html; charset=utf-8");
response.end(page);
} catch (error) {
response.statusCode = 500;
response.end("Internal Server Error");
console.error(error);
}
}).listen(3000);html не содержит <title>: заголовок уже находится в head. Приложение должно быть собрано компилятором Silent Framework — например, плагином @ivlev-dev/silent-vite — так же, как для клиентского рендера.
Гидрация на клиенте
Клиентский вход использует hydrate из @ivlev-dev/silent-core вместо mount и получает те же props, что и сервер:
import { hydrate } from "@ivlev-dev/silent-core";
import { App } from "./app.js";
const target = document.querySelector("#app");
if (target === null) {
throw new Error("#app not found");
}
void hydrate(target, App, {
props: { title: "Silent Framework" },
onMismatch: (error) => console.warn(error.message),
});hydrate не перерисовывает приложение заново: view находит свои маркеры, templateHoles занимает существующие узлы, а For, Show, Suspense, lazy и fragment адоптируют свои якоря и регионы. Маркеры data-silent-a-* снимаются с адоптированных элементов, значения применяются заново. Пока асинхронные ViewModel не завершились, серверная разметка остаётся видимой, а прелоадеры не показываются.
Заголовок страницы в серверной разметке отсутствует: клиент создаёт <title> заново и вставляет его в document.head. При несовпадении формы узла бросается HydrationMismatchError, ближайший view откатывается на клиентский рендер, а ошибка приходит в onMismatch.
Асинхронные ViewModel
renderToString создаёт корневой компонент и ждёт его ready, whenIdle и flushSync, поэтому асинхронное разрешение ViewModel через DI, границы Suspense и загрузка lazy завершаются до сериализации:
import { lazy, Suspense } from "@ivlev-dev/silent-core";
const Profile = lazy<{ id: number }>(() => import("./profile.js"));
export function App() {
return (
<Suspense fallback={<span>Загрузка...</span>}>
<Profile id={1} />
</Suspense>
);
}Сервер дожидается загрузки модуля и асинхронных view внутри границы, после чего сериализует итоговое содержимое. Опция preloader задаёт прелоадер на время рендера, а onError перехватывает ошибки компонентов: без обработчика первая ошибка отклоняет промис renderToString.
DI и жизненный цикл запроса
renderToString создаёт на каждый рендер дочерний request scope от options.container (по умолчанию — глобальный container) и передаёт его в runtime-опции корневого компонента. В конце рендера scope освобождается, даже если рендер завершился ошибкой.
singleton-привязки живут в контейнере-владельце: это process-wide состояние, общее для всех запросов. Создавайте их на общем контейнере (options.containerили глобальномcontainer) и не храните в них пользователя, tenant или другие данные запроса.scoped-привязки живут в request scope и во вложенных view-скоупах: это данные одного запроса. Экземпляры освобождаются вместе со scope, включая вызов[Symbol.dispose].singleton, фабрика которого разрешаетscoped-сервис из request scope, отклоняетсяInvalidScopeError: иначе запрос-специфичный экземпляр был бы захвачен синглтоном навсегда. Для per-request сервисов используйтеscopedи не поднимайте их в корневой контейнер.
const app = new Container("app");
app.bind(Session, () => loadSession()).inScopedScope();
app.bind(Logger, () => new Logger());
const { html } = await renderToString(App, { container: app });Прогрессивный стриминг
renderToStream(app, options) возвращает ReadableStream<string> с телом документа. В отличие от нарезки готовой строки, первый чанк — это синхронный shell, который отдаётся до завершения Suspense, lazy и асинхронных ViewModel. head отдаётся через onHead сразу вместе с shell.
import { renderToStream } from "@ivlev-dev/silent-server";
const stream = renderToStream(App, {
onHead(head, info) {
if (info.final) {
replaceHead(head);
return;
}
documentHead = head;
},
onShell(shell) {
shellLength = shell.length;
},
});
for await (const chunk of stream) {
response.write(chunk);
}
response.end();Протокол:
- Первый чанк — shell: итоговая разметка синхронной части дерева и fallback-содержимое незавершённых границ. Незавершённая граница обёрнута комментариями
<!--silent-stream:ID-->…<!--silent-stream-end:ID-->. - Когда граница
Suspense,lazyили асинхронная ViewModel готова, сервер дописывает чанк<template data-silent-stream="ID">…</template><script>window.__silentStream.patch(ID)</script>. Минимальный inline-runtime приходит один раз перед первым патчем и сам удаляет служебные узлы. - Патч заменяет содержимое между маркерами и удаляет сами маркеры. Итоговый DOM совпадает с разметкой
renderToString, поэтомуhydrateпринимает её без изменений. Вложенные границы патчатся независимо; порядок чанков сохраняется. onHead(head, { final: false })вызывается до первого чанка тела,onHead(head, { final: true })— только если асинхронная часть добавила метаданные. Приfinal: trueзамените ранее отданный head.
Опции:
| Опция | Назначение |
| --- | --- |
| onHead(head, info) | Head доступен сразу после синхронного shell; info.final сообщает, что пришло финальное значение. |
| onShell(html) | Синхронный shell до начала асинхронных патчей. |
| onChunk(chunk) | Каждый фактически записанный чанк тела. |
| chunkSize | Максимальный размер чанка; по умолчанию 16 КиБ. Патчи также режутся по этому лимиту. |
| nonce | Nonce для inline-runtime и скриптов патчей (CSP). |
| signal | Отмена доставки. Рендер завершается и освобождает ресурсы, но новые чанки не пишутся. |
Ограничения протокола:
headс асинхронных границ не может попасть в HTTP-заголовки: используйтеonHead(..., { final: true })и обновляйте head на клиенте.- Патч вставляется через
<template>; содержимое парсится в контексте body. Фрагменты, допустимые только внутри таблицы/select, требуют собственного контейнера. - Inline-runtime требует разрешённых inline-скриптов или
nonce. Без JS остаётся shell с fallback-содержимым. - Ошибка после отправки shell закрывает поток ошибкой: соединение обрывается, fallback остаётся видимым. Ошибки до shell отклоняют поток без отправки тела.
- Backpressure не учитывается: чанки буферизуются в
ReadableStream, пока читатель их не заберёт. - Поток удерживает внутреннюю очередь SSR до завершения рендера: другие
renderToString/renderToStreamждут.
renderToString не изменился: он по-прежнему ждёт всё дерево и возвращает { html, head } без служебных маркеров стриминга.
API
| Символ | Назначение |
| --- | --- |
| renderToString(app, options?) | Рендерит корневой компонент в Promise<RenderResult>; вызовы сериализуются внутренней очередью. |
| renderToStream(app, options?) | Возвращает ReadableStream<string> с прогрессивным shell и патчами границ. |
| RenderResult | Результат рендера: { html, head }. |
| RenderResult.html | Сериализованная разметка приложения без <title>, с якорями и маркерами для гидрации. |
| RenderResult.head | HTML метаданных, вынесенных из дерева, в первую очередь <title>. |
| RenderOptions | Опции рендера. |
| RenderOptions.props | Props корневого компонента. |
| RenderOptions.container | Базовый DI-контейнер; на каждый рендер от него создаётся дочерний request scope. По умолчанию — корневой контейнер @ivlev-dev/silent-di. |
| RenderOptions.preloader | Прелоадер на время рендера. |
| RenderOptions.onError | Обработчик ошибок компонентов; если не задан, первая ошибка отклоняет промис. |
Ограничения и совместимость
- Только ESM и Node.js
>=22; пакет не содержит CommonJS-сборки. - Мини-DOM реализует подмножество, необходимое шаблонам компилятора; произвольные браузерные API внутри компонентов недоступны.
- DOM-глобалы общие на процесс, поэтому параллелизм SSR внутри процесса ограничен внутренней очередью
renderToString. - Root bindings в DI общие для процесса, а
scoped-bindings изолированы request scope каждого вызоваrenderToString. - В Vite-сборке держите рантайм внешним, иначе приложение и
renderToStringполучат разные экземпляры модулей:
export default defineConfig({
plugins: [silent()],
ssr: {
external: [
"@ivlev-dev/silent-core",
"@ivlev-dev/silent-di",
"@ivlev-dev/silent-reactivity",
"@ivlev-dev/silent-server",
],
},
});- Гидрация адоптирует только значения, созданные через
template()/templateHoles(); DOM, собранный вручную, рендерится клиентски. <title>должен быть прямым потомком корневого элемента шаблона view; вложенные глубже заголовки вызывают откат к клиентскому рендеру.- Несколько заголовков одновременно не дедуплицируются — рендерите один
<title>. Заголовки внутри<svg>и сitemPropне выносятся вhead.
Ссылки
- Репозиторий: https://github.com/ivlev-dev/silent-framework
- Документация: https://github.com/ivlev-dev/silent-framework/blob/main/docs/api/core.md
- CHANGELOG: https://github.com/ivlev-dev/silent-framework/blob/main/CHANGELOG.md
- Issues: https://github.com/ivlev-dev/silent-framework/issues
MIT © ivlev-dev
