Feat/suspense module mounter by heymdall-legal · Pull Request #532 · core-ds/arui-scripts

heymdall-legal · 2026-07-06T13:25:13Z

Добавлена возможность монтировать модули через суспенс. Как на клиенте, так и на сервере.
Для серверного монтирования есть дополнительные ограничения, поэтому он реализован отдельным методом.

По сути это все добавление новой фичи и никак не ломает предыдущее использование.

Общая логика описана в docs/specs/ssr-spec.md. Собственно по этой спеке все и делалось.

Единственная реальная "недаработка" в спеке - шареный кеш для суспенса, который чисто теоретически может некорректно пошарится между разными запросами если модули из разных запросов используют абсолютно одинаковый набор параметров для модулей. Буду лечить, но отдельным пр-ом. По сути риск подобного сценария минимален.

В целом тут больше текста и тестов, чем самого реального кода.
Что в реальности реализовано:
В script-modules:

Новый апи createLazyMounter - React.lazy-совместимая фабрика. На сервере рендерит пустой
(без вызова загрузчика). На клиенте: mount с поддержкой module.update на изменение runParams.
createSsrMounter - изоморфная фабрика компонента для запихивания его в suspense. Оно уже умеет рендрится на сервере и затем корректно гидрируется на клиенте без перезапроса getModuleResources. Этот вариант НЕ умеет работать с shadowDOM.
createServerStateModuleFetcher переписан с xmlHttpRequest на fetch. Никому ничего не должно сломать, но если вдруг кто-то сидит на ie - добавляйте полифилы сами.

Остальные изменения в пакете по сути позволяют всему этому работать.

В scripts-server:

createGetModulesMethod теперь позволяет указать для модулей дополнительный метод - renderToHtml, который должен возвращать html модуля, который запрошен с чужого сервера
Для default модулей манифест теперь будет содержать стили если модуль был запрошен для серврерного рендринга. Раньше вся загрузка производилась райнтаймом вебпака. Если не добавлять серверный рендеринг все продолжает работать как раньше

В scripts:

В манифест модулей, который пишется при сборке на диск теперь будут записываться стили для default модулей. Для этого сделан плагин, который находит все чанки которые сделаны wmf.

Как вообще работает подключение модулей с SSR:

На сервере хоста

createSsrMounter рендерит ServerModule внутри <Suspense>. React приостанавливает рендер, пока не разрешится Suspense-ресурс.
Suspense-ресурс вызывает loadServerModule, которая делает getModuleResources({ ssr: { runParams } }) — запрос к серверу модуля с флагом SSR.
Сервер модуля в createGetModulesMethod видит флаг ssr, вызывает module.renderToHtml(moduleState, ssrRunParams), возвращает { html, scripts, styles, moduleState }.
Компонент рендерит:
- стили — inline <style> (default) или <link> при stylesMode: 'link'; атрибуты data-module-ssr-href и data-parent-app-id для того чтобы на клиенте рантайм не началл грузить их еще раз;
- HTML модуля в <div> c data-module-ssr-mount-id;
- JSON-payload ресурсов в <script type="application/json"> с data-module-ssr-payload.

Стили default (module federation) модулей добавляет AttributeModuleCssPlugin при сборке: обходит граф чанков и записывает css в запись модуля в манифесте. При SSR-запросе createGetModulesMethod отдаёт эти стили; для обычных запросов ответ остаётся прежним (css: []).

На клиенте

ClientModule при первом рендере захватывает snapshot серверной разметки (она уже в DOM) и рендерит её как dangerouslySetInnerHTML — React не трогает стили и payload.
Запускает лоадер, обёрнутый в createEmbeddedModuleFetcher: ищет <script type="application/json"> с data-module-ssr-payload, к сети не обращается. Если payload не найден — падает на fallback-фетчер (исходный getModuleResources).
Загружает скрипты модуля — через MF runtime (default) или <script>-теги (compat). Стили с data-module-ssr-href наследуются и не загружаются повторно.
Гидрация: если у модуля есть hydrate — вызывает его, React гидрирует существующую разметку. Если нет — очищает innerHTML монтируемого узла и вызывает mount (graceful degradation, warning в dev).
Обновление: при изменении runParams вызывает module.update(target, params, state) — без перемонтирования.

Prerelease versions:

@alfalab/scripts-modules@0.0.0-next-20260709074302
@alfalab/scripts-server@0.0.0-next-20260709074302
arui-scripts@0.0.0-next-20260709074302

- fetchResources adopts server-emitted module styles (data-module-ssr-href) instead of removing and re-fetching them, avoiding FOUC - add createEmbeddedModuleFetcher: reads resources from embedded payload - useModuleMounter/createLazyMounter call module.update() on runParams change when available, falling back to remount otherwise - export MODULE_SSR_HREF_ATTRIBUTE

Isomorphic component exported from @alfalab/scripts-modules/ssr. - server: suspends on getModuleResources with ssr flag, inlines module styles, renders module html into an outlet, embeds resources payload - client: reads embedded payload (no duplicate resources request), hydrates server markup via module.hydrate (or mounts when absent), calls module.update on runParams change, cleans up on unmount - client loader is built internally wrapping the fetcher in createEmbeddedModuleFetcher, so the resources endpoint is not called twice - add exports map (root '.' unchanged, new './ssr' subpath) - export MODULE_SSR_ROOT_ATTRIBUTE and MODULE_SSR_MOUNT_ID_ATTRIBUTE - round-trip test: renderToPipeableStream -> serialize -> jsdom hydrate

Document in the ssr spec why createSsrMounter shipped without the fallback prop (server/client hydration-consistency problem), the process-global suspense cache trade-offs (cross-request sharing, no abort wiring), and the unused link-mode style adoption path. Also note that the factory builds its client loader internally, superseding the §5.3 passed-in-loader signature.

changeset-bot · 2026-07-06T13:25:17Z

🦋 Changeset detected

Latest commit: 331ff34

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@alfalab/scripts-modules	Minor
@alfalab/scripts-server	Minor
arui-scripts	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

qrik116 · 2026-07-10T10:35:13Z

Сложно полноценно в голове скомпилировать работу и что-то дельное найти, выглядит классно

dmitrbrvsk · 2026-07-12T14:53:36Z

    const previouslyAddedStyles = Array.from(
        cssTargetNode.querySelectorAll(`${styleTag}[${DATA_APP_ID_ATTRIBUTE}="${moduleId}"]`),
-    );
+    ).filter((style) => !adoptedStyleTags.includes(style));


а после добавление логики с filter разве подходит название для перемнной previouslyAddedStyles?)

dmitrbrvsk · 2026-07-12T14:57:18Z

        const moduleVendorFiles = manifest[`vendor-${moduleId}`] || {};

+        // js/css в манифесте могут быть строкой или массивом, нормализуем в плоский список.
+        const toArray = (value: string | string[] | undefined): string[] => {


это вроде бы можно вынести за createModuleFetcher
чтобы каждый не создавался toArray при вызове createModuleFetcher

dmitrbrvsk · 2026-07-12T15:06:03Z

+
+        link.addEventListener('load', finish);
+        link.addEventListener('error', finish);
+        abortSignal?.addEventListener('abort', finish);


может не увидел, но кажется нигде не очищаются listener при размонтировании модуля
(остается в памяти)

dmitrbrvsk · 2026-07-12T15:08:25Z

+        const hadServerHtmlRef = useRef(false);
+
+        if (snapshotRef.current === null) {
+            const { snapshot, hadServerHtml } = readServerMarkup(instanceId);


а это окей что вызывается readServerMarkup во время ренндера?
как будто это нужно вызывать в useEffect

useEffect(() => {.....}, [instanceId])

dmitrbrvsk · 2026-07-12T15:10:54Z

+`ssrRunParams` должны быть JSON-сериализуемыми. В них передаётся только то, от чего зависит
+серверная разметка модуля. Клиентские значения вроде callback, ref или DOM-объектов передаются
+только в `runParams` и доступны модулю на этапе `hydrate`/`mount`/`update`. Если один и тот же
+модуль рендерится на странице несколько раз, передавайте стабильный `instanceId`.


предлагаю давать warning в консоль для таких случаев, когда ssrRunParams одинаковые есть

dmitrbrvsk · 2026-07-12T15:19:11Z

        });
+
+        if (!response.ok) {
+            throw new Error(response.statusText);


может тут еще возвращать и тело ответа? там бывает полезная инфа для клиента

dmitrbrvsk · 2026-07-12T15:34:02Z

+// поэтому между запросами данные не переиспользуются (важно: moduleState может зависеть
+// от запроса). Все чтения в рамках одного синхронного прохода рендера происходят до
+// отложенного удаления.
+const cache = new Map<string, CacheEntry<unknown>>();


ты хоть в описании ПРа написал, что тут осталась недоработки с шаренным кэшом
то что два пользователя гипотитечски могут увидеть не свои данные
может хотя бы добавить айдишник request для ключа в cache?
const key =${requestId}_${key}``

Heymdall added 20 commits July 6, 2026 00:16

chore(*): upgrade ts version

c9d1bc7

feat(modules): add createLazyMounter helper

dd335a8

feat(modules): middle of implementaiton, not working

4315dfd

feat(modules): middle of implementaiton, not working

2302f13

docs(modules): create a spec for server side rendering modules

45c342b

test(module-loader): working tests for lazy mounter

1a3535e

feat(modules): make fetcher and lazy mounter ssr-safe

adb207c

fix(example): use css prefix to render module content

8d1679f

feat(modules): add ssr contracts

50c27c7

docs(*): add SSR modules examples

083826a

docs(modules): plan ssr stylesheet link mode

c8ffac9

chore(examples): fix eslint error

5324d35

docs(modules): ssr stylesheet plan fixes

f1a059c

feat(ssr): add stylesheet link mode

bacab43

test(ssr): cover adopted stylesheet links

8b00d92

docs(ssr): document stylesheet link mode

d3a548a

docs(*): finalize changeset files

c707d89

Heymdall added 3 commits July 8, 2026 17:33

docs(ssr-spec): additional task to work with wmf styles loading

696c933

feat(modules): load wmf styles in ssr modules

8ec9e99

docs(*): updated changesets

331ff34

heymdall-legal marked this pull request as ready for review July 9, 2026 14:19

qrik116 approved these changes Jul 10, 2026

View reviewed changes

dmitrbrvsk self-requested a review July 12, 2026 15:14

dmitrbrvsk reviewed Jul 13, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Feat/suspense module mounter - #532

Feat/suspense module mounter#532
heymdall-legal wants to merge 23 commits into
masterfrom
feat/suspense-module-mounter

heymdall-legal commented Jul 6, 2026 •

edited

Loading

Uh oh!

changeset-bot Bot commented Jul 6, 2026 •

edited

Loading

Uh oh!

qrik116 commented Jul 10, 2026

Uh oh!

dmitrbrvsk Jul 12, 2026

Uh oh!

dmitrbrvsk Jul 12, 2026

Uh oh!

dmitrbrvsk Jul 12, 2026

Uh oh!

dmitrbrvsk Jul 12, 2026

Uh oh!

dmitrbrvsk Jul 12, 2026

Uh oh!

dmitrbrvsk Jul 12, 2026

Uh oh!

dmitrbrvsk Jul 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Conversation

heymdall-legal commented Jul 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Как вообще работает подключение модулей с SSR:

Prerelease versions:

Uh oh!

changeset-bot Bot commented Jul 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

qrik116 commented Jul 10, 2026

Uh oh!

dmitrbrvsk Jul 12, 2026

Choose a reason for hiding this comment

Uh oh!

dmitrbrvsk Jul 12, 2026

Choose a reason for hiding this comment

Uh oh!

dmitrbrvsk Jul 12, 2026

Choose a reason for hiding this comment

Uh oh!

dmitrbrvsk Jul 12, 2026

Choose a reason for hiding this comment

Uh oh!

dmitrbrvsk Jul 12, 2026

Choose a reason for hiding this comment

Uh oh!

dmitrbrvsk Jul 12, 2026

Choose a reason for hiding this comment

Uh oh!

dmitrbrvsk Jul 12, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

heymdall-legal commented Jul 6, 2026 •

edited

Loading

changeset-bot Bot commented Jul 6, 2026 •

edited

Loading