npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@ivlev-dev/silent-server

v0.12.0

Published

Server-side rendering for Silent Framework without DOM dependencies

Readme

@ivlev-dev/silent-server

SSR для Silent Framework без jsdom и linkedom: собственный мини-DOM, асинхронные ViewModel и гидрация серверной разметки.

npm version license node

Возможности

  • 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-server
npm install @ivlev-dev/silent-server
yarn 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();

Протокол:

  1. Первый чанк — shell: итоговая разметка синхронной части дерева и fallback-содержимое незавершённых границ. Незавершённая граница обёрнута комментариями <!--silent-stream:ID-->…<!--silent-stream-end:ID-->.
  2. Когда граница Suspense, lazy или асинхронная ViewModel готова, сервер дописывает чанк <template data-silent-stream="ID">…</template><script>window.__silentStream.patch(ID)</script>. Минимальный inline-runtime приходит один раз перед первым патчем и сам удаляет служебные узлы.
  3. Патч заменяет содержимое между маркерами и удаляет сами маркеры. Итоговый DOM совпадает с разметкой renderToString, поэтому hydrate принимает её без изменений. Вложенные границы патчатся независимо; порядок чанков сохраняется.
  4. 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