@ivlev-dev/silent-server 0.1.1 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +163 -0
- package/dist/index.d.ts +1 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -0
- package/dist/index.js.map +1 -1
- package/dist/stream.d.ts +8 -0
- package/dist/stream.d.ts.map +1 -0
- package/dist/stream.js +30 -0
- package/dist/stream.js.map +1 -0
- package/package.json +4 -4
package/README.md
ADDED
|
@@ -0,0 +1,163 @@
|
|
|
1
|
+
# @ivlev-dev/silent-server
|
|
2
|
+
|
|
3
|
+
SSR для Silent Framework без jsdom и linkedom: собственный мини-DOM, асинхронные ViewModel и гидрация серверной разметки.
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/@ivlev-dev/silent-server)
|
|
6
|
+
[](https://github.com/ivlev-dev/silent-framework/blob/main/LICENSE)
|
|
7
|
+
[](https://www.npmjs.com/package/@ivlev-dev/silent-server)
|
|
8
|
+
|
|
9
|
+
## Возможности
|
|
10
|
+
|
|
11
|
+
- `renderToString` возвращает `{ html, head }`: разметку приложения и метаданные для `<head>`.
|
|
12
|
+
- Собственный мини-DOM: парсер шаблонов компилятора, документ, `TreeWalker` и сериализатор без внешних DOM-зависимостей.
|
|
13
|
+
- Асинхронные ViewModel, `Suspense` и `lazy` дожидаются до сериализации — в результат попадает итоговое содержимое.
|
|
14
|
+
- `<title>` из любого компонента выносится из дерева в `RenderResult.head`, как в React 19.
|
|
15
|
+
- Серверные якоря и маркеры `data-silent-a-*` сохраняются для адоптации узлов при `hydrate`.
|
|
16
|
+
- Вызовы сериализуются внутренней очередью, а DOM-глобалы живут только на время рендера.
|
|
17
|
+
|
|
18
|
+
## Установка
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
pnpm add @ivlev-dev/silent-server
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
npm install @ivlev-dev/silent-server
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
yarn add @ivlev-dev/silent-server
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
Пакет поставляется как ESM с объявлениями типов и требует Node.js 22 или новее.
|
|
33
|
+
|
|
34
|
+
## Быстрый старт
|
|
35
|
+
|
|
36
|
+
```ts
|
|
37
|
+
import { createServer } from "node:http";
|
|
38
|
+
import { renderToString } from "@ivlev-dev/silent-server";
|
|
39
|
+
import { App } from "./app.js";
|
|
40
|
+
|
|
41
|
+
createServer(async (request, response) => {
|
|
42
|
+
try {
|
|
43
|
+
const { html, head } = await renderToString(App, {
|
|
44
|
+
props: { title: "Silent Framework" },
|
|
45
|
+
});
|
|
46
|
+
|
|
47
|
+
const page = `<!doctype html>
|
|
48
|
+
<html lang="ru">
|
|
49
|
+
<head>
|
|
50
|
+
<meta charset="utf-8" />
|
|
51
|
+
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
|
52
|
+
${head}
|
|
53
|
+
</head>
|
|
54
|
+
<body>
|
|
55
|
+
<div id="app">${html}</div>
|
|
56
|
+
<script type="module" src="/client.js"></script>
|
|
57
|
+
</body>
|
|
58
|
+
</html>`;
|
|
59
|
+
|
|
60
|
+
response.setHeader("content-type", "text/html; charset=utf-8");
|
|
61
|
+
response.end(page);
|
|
62
|
+
} catch (error) {
|
|
63
|
+
response.statusCode = 500;
|
|
64
|
+
response.end("Internal Server Error");
|
|
65
|
+
console.error(error);
|
|
66
|
+
}
|
|
67
|
+
}).listen(3000);
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
`html` не содержит `<title>`: заголовок уже находится в `head`. Приложение должно быть собрано компилятором Silent Framework — например, плагином `@ivlev-dev/silent-vite` — так же, как для клиентского рендера.
|
|
71
|
+
|
|
72
|
+
## Гидрация на клиенте
|
|
73
|
+
|
|
74
|
+
Клиентский вход использует `hydrate` из `@ivlev-dev/silent-core` вместо `mount` и получает те же `props`, что и сервер:
|
|
75
|
+
|
|
76
|
+
```ts
|
|
77
|
+
import { hydrate } from "@ivlev-dev/silent-core";
|
|
78
|
+
import { App } from "./app.js";
|
|
79
|
+
|
|
80
|
+
const target = document.querySelector("#app");
|
|
81
|
+
if (target === null) {
|
|
82
|
+
throw new Error("#app not found");
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
void hydrate(target, App, {
|
|
86
|
+
props: { title: "Silent Framework" },
|
|
87
|
+
onMismatch: (error) => console.warn(error.message),
|
|
88
|
+
});
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
`hydrate` не перерисовывает приложение заново: view находит свои маркеры, `templateHoles` занимает существующие узлы, а `For`, `Show`, `Suspense`, `lazy` и `fragment` адоптируют свои якоря и регионы. Маркеры `data-silent-a-*` снимаются с адоптированных элементов, значения применяются заново. Пока асинхронные ViewModel не завершились, серверная разметка остаётся видимой, а прелоадеры не показываются.
|
|
92
|
+
|
|
93
|
+
Заголовок страницы в серверной разметке отсутствует: клиент создаёт `<title>` заново и вставляет его в `document.head`. При несовпадении формы узла бросается `HydrationMismatchError`, ближайший view откатывается на клиентский рендер, а ошибка приходит в `onMismatch`.
|
|
94
|
+
|
|
95
|
+
## Асинхронные ViewModel
|
|
96
|
+
|
|
97
|
+
`renderToString` создаёт корневой компонент и ждёт его `ready`, `whenIdle` и `flushSync`, поэтому асинхронное разрешение ViewModel через DI, границы `Suspense` и загрузка `lazy` завершаются до сериализации:
|
|
98
|
+
|
|
99
|
+
```tsx
|
|
100
|
+
import { lazy, Suspense } from "@ivlev-dev/silent-core";
|
|
101
|
+
|
|
102
|
+
const Profile = lazy<{ id: number }>(() => import("./profile.js"));
|
|
103
|
+
|
|
104
|
+
export function App() {
|
|
105
|
+
return (
|
|
106
|
+
<Suspense fallback={<span>Загрузка...</span>}>
|
|
107
|
+
<Profile id={1} />
|
|
108
|
+
</Suspense>
|
|
109
|
+
);
|
|
110
|
+
}
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
Сервер дожидается загрузки модуля и асинхронных view внутри границы, после чего сериализует итоговое содержимое. Опция `preloader` задаёт прелоадер на время рендера, `container` — DI-контейнер корневого view, а `onError` перехватывает ошибки компонентов: без обработчика первая ошибка отклоняет промис `renderToString`.
|
|
114
|
+
|
|
115
|
+
## API
|
|
116
|
+
|
|
117
|
+
| Символ | Назначение |
|
|
118
|
+
| --- | --- |
|
|
119
|
+
| `renderToString(app, options?)` | Рендерит корневой компонент в `Promise<RenderResult>`; вызовы сериализуются внутренней очередью. |
|
|
120
|
+
| `RenderResult` | Результат рендера: `{ html, head }`. |
|
|
121
|
+
| `RenderResult.html` | Сериализованная разметка приложения без `<title>`, с якорями и маркерами для гидрации. |
|
|
122
|
+
| `RenderResult.head` | HTML метаданных, вынесенных из дерева, в первую очередь `<title>`. |
|
|
123
|
+
| `RenderOptions` | Опции рендера. |
|
|
124
|
+
| `RenderOptions.props` | Props корневого компонента. |
|
|
125
|
+
| `RenderOptions.container` | DI-контейнер корневого view; по умолчанию корневой контейнер `@ivlev-dev/silent-di`. |
|
|
126
|
+
| `RenderOptions.preloader` | Прелоадер на время рендера. |
|
|
127
|
+
| `RenderOptions.onError` | Обработчик ошибок компонентов; если не задан, первая ошибка отклоняет промис. |
|
|
128
|
+
|
|
129
|
+
## Ограничения и совместимость
|
|
130
|
+
|
|
131
|
+
- Только ESM и Node.js `>=22`; пакет не содержит CommonJS-сборки.
|
|
132
|
+
- Мини-DOM реализует подмножество, необходимое шаблонам компилятора; произвольные браузерные API внутри компонентов недоступны.
|
|
133
|
+
- DOM-глобалы общие на процесс, поэтому параллелизм SSR внутри процесса ограничен внутренней очередью `renderToString`.
|
|
134
|
+
- В Vite-сборке держите рантайм внешним, иначе приложение и `renderToString` получат разные экземпляры модулей:
|
|
135
|
+
|
|
136
|
+
```ts
|
|
137
|
+
export default defineConfig({
|
|
138
|
+
plugins: [silent()],
|
|
139
|
+
ssr: {
|
|
140
|
+
external: [
|
|
141
|
+
"@ivlev-dev/silent-core",
|
|
142
|
+
"@ivlev-dev/silent-di",
|
|
143
|
+
"@ivlev-dev/silent-reactivity",
|
|
144
|
+
"@ivlev-dev/silent-server",
|
|
145
|
+
],
|
|
146
|
+
},
|
|
147
|
+
});
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
- Гидрация адоптирует только значения, созданные через `template()`/`templateHoles()`; DOM, собранный вручную, рендерится клиентски.
|
|
151
|
+
- `<title>` должен быть прямым потомком корневого элемента шаблона view; вложенные глубже заголовки вызывают откат к клиентскому рендеру.
|
|
152
|
+
- Несколько заголовков одновременно не дедуплицируются — рендерите один `<title>`. Заголовки внутри `<svg>` и с `itemProp` не выносятся в `head`.
|
|
153
|
+
|
|
154
|
+
## Ссылки
|
|
155
|
+
|
|
156
|
+
- Репозиторий: https://github.com/ivlev-dev/silent-framework
|
|
157
|
+
- Документация: https://github.com/ivlev-dev/silent-framework/blob/main/docs/api/core.md
|
|
158
|
+
- CHANGELOG: https://github.com/ivlev-dev/silent-framework/blob/main/CHANGELOG.md
|
|
159
|
+
- Issues: https://github.com/ivlev-dev/silent-framework/issues
|
|
160
|
+
|
|
161
|
+
---
|
|
162
|
+
|
|
163
|
+
MIT © ivlev-dev
|
package/dist/index.d.ts
CHANGED
package/dist/index.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,aAAa,CAAC"}
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,aAAa,CAAC;AACpF,OAAO,EAAE,cAAc,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC"}
|
package/dist/index.js
CHANGED
package/dist/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAyC,MAAM,aAAa,CAAC"}
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAyC,MAAM,aAAa,CAAC;AACpF,OAAO,EAAE,cAAc,EAAsB,MAAM,aAAa,CAAC"}
|
package/dist/stream.d.ts
ADDED
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
import type { AnyComponent } from "@ivlev-dev/silent-core";
|
|
2
|
+
import { type RenderOptions } from "./render.js";
|
|
3
|
+
export interface StreamOptions extends RenderOptions {
|
|
4
|
+
readonly chunkSize?: number;
|
|
5
|
+
readonly onHead?: (head: string) => void;
|
|
6
|
+
}
|
|
7
|
+
export declare function renderToStream(app: AnyComponent, options?: StreamOptions): ReadableStream<string>;
|
|
8
|
+
//# sourceMappingURL=stream.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../src/stream.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAkB,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjE,MAAM,WAAW,aAAc,SAAQ,aAAa;IAClD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC1C;AAID,wBAAgB,cAAc,CAC5B,GAAG,EAAE,YAAY,EACjB,OAAO,GAAE,aAAkB,GAC1B,cAAc,CAAC,MAAM,CAAC,CA2BxB"}
|
package/dist/stream.js
ADDED
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
import { renderToString } from "./render.js";
|
|
2
|
+
const DEFAULT_CHUNK_SIZE = 16 * 1024;
|
|
3
|
+
export function renderToStream(app, options = {}) {
|
|
4
|
+
const chunkSize = options.chunkSize !== undefined && options.chunkSize > 0
|
|
5
|
+
? options.chunkSize
|
|
6
|
+
: DEFAULT_CHUNK_SIZE;
|
|
7
|
+
const onHead = options.onHead;
|
|
8
|
+
const renderOptions = {
|
|
9
|
+
...(options.props !== undefined ? { props: options.props } : {}),
|
|
10
|
+
...(options.container !== undefined ? { container: options.container } : {}),
|
|
11
|
+
...(options.preloader !== undefined ? { preloader: options.preloader } : {}),
|
|
12
|
+
...(options.onError !== undefined ? { onError: options.onError } : {}),
|
|
13
|
+
};
|
|
14
|
+
return new ReadableStream({
|
|
15
|
+
async start(controller) {
|
|
16
|
+
try {
|
|
17
|
+
const { html, head } = await renderToString(app, renderOptions);
|
|
18
|
+
onHead?.(head);
|
|
19
|
+
for (let index = 0; index < html.length; index += chunkSize) {
|
|
20
|
+
controller.enqueue(html.slice(index, index + chunkSize));
|
|
21
|
+
}
|
|
22
|
+
controller.close();
|
|
23
|
+
}
|
|
24
|
+
catch (error) {
|
|
25
|
+
controller.error(error);
|
|
26
|
+
}
|
|
27
|
+
},
|
|
28
|
+
});
|
|
29
|
+
}
|
|
30
|
+
//# sourceMappingURL=stream.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"stream.js","sourceRoot":"","sources":["../src/stream.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAsB,MAAM,aAAa,CAAC;AAOjE,MAAM,kBAAkB,GAAG,EAAE,GAAG,IAAI,CAAC;AAErC,MAAM,UAAU,cAAc,CAC5B,GAAiB,EACjB,OAAO,GAAkB,EAAE;IAE3B,MAAM,SAAS,GACb,OAAO,CAAC,SAAS,KAAK,SAAS,IAAI,OAAO,CAAC,SAAS,GAAG,CAAC;QACtD,CAAC,CAAC,OAAO,CAAC,SAAS;QACnB,CAAC,CAAC,kBAAkB,CAAC;IACzB,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAC9B,MAAM,aAAa,GAAkB;QACnC,GAAG,CAAC,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAChE,GAAG,CAAC,OAAO,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5E,GAAG,CAAC,OAAO,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5E,GAAG,CAAC,OAAO,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACvE,CAAC;IAEF,OAAO,IAAI,cAAc,CAAS;QAChC,KAAK,CAAC,KAAK,CAAC,UAAU;YACpB,IAAI,CAAC;gBACH,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,MAAM,cAAc,CAAC,GAAG,EAAE,aAAa,CAAC,CAAC;gBAChE,MAAM,EAAE,CAAC,IAAI,CAAC,CAAC;gBACf,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC,MAAM,EAAE,KAAK,IAAI,SAAS,EAAE,CAAC;oBAC5D,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,SAAS,CAAC,CAAC,CAAC;gBAC3D,CAAC;gBACD,UAAU,CAAC,KAAK,EAAE,CAAC;YACrB,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,UAAU,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YAC1B,CAAC;QACH,CAAC;KACF,CAAC,CAAC;AACL,CAAC"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@ivlev-dev/silent-server",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.2.0",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"sideEffects": false,
|
|
6
6
|
"main": "./dist/index.js",
|
|
@@ -15,9 +15,9 @@
|
|
|
15
15
|
"dist"
|
|
16
16
|
],
|
|
17
17
|
"dependencies": {
|
|
18
|
-
"@ivlev-dev/silent-core": "0.
|
|
19
|
-
"@ivlev-dev/silent-di": "0.
|
|
20
|
-
"@ivlev-dev/silent-reactivity": "0.
|
|
18
|
+
"@ivlev-dev/silent-core": "0.2.0",
|
|
19
|
+
"@ivlev-dev/silent-di": "0.2.0",
|
|
20
|
+
"@ivlev-dev/silent-reactivity": "0.2.0"
|
|
21
21
|
},
|
|
22
22
|
"devDependencies": {
|
|
23
23
|
"jsdom": "^31.0.0",
|