arui-scripts 14.5.0-feat-modules.2 → 14.5.0-feat-modules.3

package/docs/modules.md

@@ -1,58 +1,29 @@
-# Модули приложений
-
-## Мотивация
+# Что такое модули
 Модули приложений предназначены для решения простой проблемы - переиспользование фронтового кода между приложениями.
 
 В целом, для того чтобы переиспользовать код у нас есть много разных способов, например:
 - копировать код из одного приложения в другое. Быстро, но неудобно и неэффективно.
 - выносить код в отдельный пакет и подключать его через npm. Понятный и достаточно удобный вариант,
-но ограничивает нас в скорости изменений. Если мы хотим заменить обновить код в пакете, процесс
-раскатки этого обновления на все приложения может занять много времени.
+  но ограничивает нас в скорости изменений. Если мы хотим заменить обновить код в пакете, процесс
+  раскатки этого обновления на все приложения может занять много времени.
 - Сделать так, чтобы мы могли подключать код из других приложений в свое. При этом мы получаем
-возможность быстро изменить общий код только в одном месте, а все приложения автоматически получат
-обновления.
+  возможность быстро изменить общий код только в одном месте, а все приложения автоматически получат
+  обновления.
 
 Модули позволяют реализовать именно последний вариант. Если вы знакомы с концепцией [module federation](https://webpack.js.org/concepts/module-federation/),
 то модули приложений - это его реализация в рамках arui-scripts, с дополнительным уровнем абстракции, который, в том числе,
 позволяет использовать модули без самого module-federation.
 
+## Общие принципы работы модулей
+С точки зрения кода модуль представляет собой простой js-объект, который может быть _каким то образом_ подключен в другое приложение.
 
-## Общие принципы
-Модуль - это некоторая совокупность js и css файлов, которые можно подключить в приложение. У модуля есть
-входная точка - js файл, код которого будет являться его публичным api.
-
-Для подключения модулей в приложение предоставляется набор библиотек, которые позволяют указать, какой модуль
-и куда надо подключить.
-
-## Типы модулей
-Несмотря на кажущуюся простоту концепции, можно представить разные сценарии использования модулей. В ряде случаев
-мы хотим просто предоставить доступ к коду из другого приложения, в других - мы хотим иметь возможность
-настраивать поведение модуля в зависимости от приложения, в котором он используется. Или мы хотим сделать так, чтобы
-наш модуль мог сразу же получить какие-то данные с сервера, потому что его поведение зависит от этих данных.
-
-Из-за того, что эти сценарии различаются, мы выделили два типа модулей:
-
-- Клиентские модули. Это модули, которые имеют только клиентскую часть.
-- Модули с серверной частью. Это модули, которые имеют как клиентскую, так и серверную часть. Серверная часть может
-реализовывать какую-то логику, которая не может быть реализована на клиенте, например отдавать разные модули в зависимости
-от пользователя, получать предподготовленные данные с сервера и т.д.
-
-### Сравнение
-
-Клиентские модули:
-- Можно реализовать в любом приложении, даже если у него нет серверной части.
-- Меньше кода, меньше проблем с поддержкой.
-- Немного проще подключение модуля в приложение-хост.
-
-Модули с серверной частью:
-- Можно реализовать дополнительную логику, которая не может быть реализована на клиенте.
-- Возможность изменить режим подключения модуля без изменений на приложениях-хостах.
+`arui-scripts` предоставляет решение для сборки таких модулей, а также отдельную библиотеку для упрощения их подключения в другие приложения.
 
 ## Режимы подключения модулей
 
-Кроме того, модули делятся еще и по способу их подключения:
-- `mf` модули. Это модули, которые подключаются с помощью [webpack module federation](https://webpack.js.org/concepts/module-federation/).
-- `embedded` модули. Такие модули подключаются просто через добавление нужных скриптов на страницу приложения.
+В `arui-scripts` есть два способа сборки модулей:
+- `mf` -  Это модули, которые подключаются с помощью [webpack module federation](https://webpack.js.org/concepts/module-federation/).
+- `embedded` - Это модули, которые подключаются просто добавлением нужных скриптов на страницу.
 
 Основная проблема, которую решает ModuleFederation - это возможность не загружать на хост-приложение код библиотек уже подключенных в него.
 Например, хост-приложение уже использует `react`, модуль так же написан на `react`. ModuleFederation дает нам легко "переиспользовать"
@@ -74,6 +45,43 @@
 - **+++** Встроенная изоляция стилей. Стили модуля не будут применены к хост-приложению, если только вы не захотите этого.
 - **---** Нет возможности использовать разные версии общих библиотек в разных модулях/хостах, если вы хотите их шарить.
 
+## Возможность управления модулями с сервера
+Сами модули используются только на клиентской части приложения. Но, в некоторых случаях, может быть полезно иметь возможность
+управлять тем, какой модуль должен быть подключен на странице с сервера, или же иметь модуль, который будет при загрузке
+иметь доступ к данным, доступным только на сервере (аналогично тому, как мы передаем серверный стейт в приложения при SSR).
+
+Поэтому `arui-scripts` предоставляет возможность создать специальный эндпоинт на вашем сервере, из которого вы сможете управлять
+состоянием модуля.
+
+Модули с такой возможностью мы называем _серверными модулями_ (обычные модули мы называем _клиентскими_).
+
+## Особые типы модулей
+Несмотря на то, что сами по себе модули представляют собой простой js-объект, мы определяем один особый тип модулей - _монтируемые модули_.
+
+### Монтируемые модули
+Монтируемые модули - это модули, основное предназначение которых - отрендерить какой-то компонент внутри хост-приложения.
+Монтируемые модули могут быть как клиентскими, так и серверными.
+
+Такие модули должны экспортировать две функции:
+
+```tsx
+export function mount(targetNode, runParams, serverState): void {
+    // здесь происходит монтирование модуля в хост-приложение
+    // targetNode - это DOM-нода, в которую нужно отрендерить модуль
+    // runParams - это параметры, которые были переданы при запуске модуля
+    // serverState - это состояние, которое было передано с сервера
+
+    // Скорее всего это будет что-то вроде:
+    ReactDOM.render(<App preparedState={serverState} runParams={runParams} />, targetNode);
+}
+
+export function unmount(targetNode): void {
+    // здесь происходит демонтирование модуля из хост-приложения
+    // Скорее всего это будет что-то вроде:
+    ReactDOM.unmountComponentAtNode(targetNode);
+}
+```
+
 ## Как создать модуль
 
 ### Описать модуль в настройках arui-scripts
@@ -119,57 +127,54 @@ export default aruiScriptsConfig;
 Все параметры конфигурации описаны [ниже](#Конфигурация-модулей).
 
 ### Создать модуль
-Модуль является простым js/ts файлом, который следует простой договоренности:
-
-`embedded` модули должны писать в window свой объект, который содержит функции для монтирования и демонтирования модуля.
+Модуль является простым js/ts файлом. Он может использовать любой код вашего проекта, и любые библиотеки из node_modules.
 
-```tsx
-import type { // Обратите внимание на `import type` - наш в модель никак не использует код библиотеки, нам нужны только типы
-    ModuleMountFunction,
-    ModuleUnmountFunction,
-    WindowWithMountableModule
-} from '@alfalab/scripts-modules';
-
-const mountModule: ModuleMountFunction = (moduleId, params, targetNode) => {
-    // здесь мы можем отрендерить наш модуль в targetNode
-    // например:
-    ReactDOM.render(<App />, targetNode);
-};
+В зависимости от режима подключения модуля, входная точка будет выглядеть по разному.
 
-const unmountModule: ModuleUnmountFunction = (targetNode) => {
-    // здесь мы можем отключить наш модуль от targetNode
-    // например:
-    ReactDOM.unmountComponentAtNode(targetNode);
-};
+#### Embedded модуль
+Входная точка embedded модуля должна писать в глобальную переменную `window` объект с ключом `{НазваниеМодуля}`.
+Все поля этого объекта по сути и будут являться модулем, ваши потребители смогут использовать их.
 
+```ts
+// src/modules/client-module-embedded/index.ts
 
-// ClientModuleEmbedded - имя модуля, которое мы указали в настройках arui-scripts
-(window as WindowWithMountableModule).ClientModuleEmbedded = {
-    mount: mountModule,
-    unmount: unmountModule,
+window.ClientModuleEmbedded = {
+    doSomething: () => {
+        console.log('Hello from embedded module!');
+    },
+    publicConstant: 3.14,
+    // ...
 };
 ```
 
-Если у вас возникает вопрос "фу, разве не плохо писать в window?". Ответ: да, плохо. Но вы думаете что ModuleFederation
-работает как то иначе? По сути мы просто воспроизводим то же самое поведение, только в более ручном режиме.
+<details>
+<summary>Писать в window? Вы что, с дуба рухнулись?</summary>
+Да, конечно, это может создать определенные проблемы (конфликты имен модулей, определенные ограничения на используемые названия),
+но по сути это единственный способ передать код модуля в хост-приложение.
 
-`mf` модули не должны ничего писать в window (на самом деле за них то же самое делает webpack). Они должны просто
-экспортировать функции `mount` и `unmount`:
+Webpack module federation делает абсолютно то же самое, просто прячет работу с глобальными переменными за собой.
+</details>
 
-```tsx
-import type { ModuleMountFunction, ModuleUnmountFunction } from '@alfalab/scripts-modules';
+#### MF модуль
+Входная точка MF модуля должна экспортировать все поля модуля через `export`.
 
-export const mount: ModuleMountFunction = (moduleId, params, targetNode) => {
-    // здесь мы можем отрендерить наш модуль в targetNode
-    // например:
-    ReactDOM.render(<App />, targetNode);
-};
+```ts
+// src/modules/client-module-mf/index.ts
 
-export const unmount: ModuleUnmountFunction = (targetNode) => {
-    // здесь мы можем отключить наш модуль от targetNode
-    // например:
-    ReactDOM.unmountComponentAtNode(targetNode);
+export const doSomething = () => {
+    console.log('Hello from mf module!');
 };
+
+export const publicConstant = 3.14;
+```
+
+#### Создание модулей предопределенного типа
+
+**Монтируемый модуль, mf**
+
+```ts
+// src/modules/client-module-mf/index.ts
+
 ```
 
 ### (Опционально) Определить серверный эндпоинт для модуля
@@ -185,7 +190,8 @@ const modules: ModulesConfig = {
         version: '1.0.0',
         getRunParams: async (getResourcesRequest) => ({
             // getResouresRequest - это объект, который будет передан из хост-приложения
-            // данные, которые вернет эта функция будут переданы в mount функцию модуля
+
+            // данные, которые вернет эта будут доступны при инициализации модуля
             paramFromServer: 'This can be any data from server',
             asyncData: 'It can be constructed from async data, so you may perform some service calls here',
             contextRoot: 'http://localhost:8081',
@@ -203,6 +209,8 @@ const modules: ModulesConfig = {
 };
 ```
 
+Подробнее о `getResourcesRequest` и `getRunParams` рассказано в разделе [Подключение модулей](#Подключение-модулей).
+
 Далее, в зависимости от того, какой серверный фреймворк вы используете, вам нужно будет подключить ваши модули в
 соответствующий хендлер. Например, для express это будет выглядеть так:
 
@@ -214,7 +222,7 @@ const modulesRouter = createGetModulesExpress(modules);
 app.use(modulesRouter);
 ```
 
-Для hapi@16:
+Для `hapi@16`:
 
 ```ts
 import { createGetModulesHapi16Plugin } from '@alfalab/scripts-server/build/hapi16';
@@ -224,7 +232,7 @@ const modulesPlugin = createGetModulesHapi16Plugin(modules);
 server.register(modulesPlugin);
 ```
 
-Для hapi@20:
+Для `hapi@20`:
 
 ```ts
 import { createGetModulesHapi20Plugin } from '@alfalab/scripts-server/build/hapi20';
@@ -269,155 +277,163 @@ type ModulesMethod = {
 Никакого встроенного механизма изоляции стилей для MF модулей нет. Если хост-приложение и модуль используют css-modules,
 то конфликтов возникнуть не должно. Если же это не так - вы можете попробовать решить эту проблему используя shadow-dom.
 
-### Тестирование модулей
+### TODO: тестирование модулей
 
-TODO
+# Подключение модулей
 
+## Создание загрузчика
+Базовый способ подключение модулей - это использование `createModuleLoader` из `@alfalab/scripts-modules`. Этот метод
+вернет вам функцию, которая позволит подключить модуль в ваше приложение.
 
-## Подключение модулей в хост-приложение
+```ts
+import { createModuleLoader } from '@alfalab/scripts-modules';
+
+const loader = createModuleLoader({
+    moduleId: 'test', // id модуля, который вы хотите подключить
+    // функция, которая должна вернуть описание модуля.
+    getModuleResources: async ({ moduleId, hostAppId, params }) => ({
+        scripts: ['http://localhost:8081/static/js/main.js'], // скрипты модуля
+        styles: ['http://localhost:8081/static/css/main.css'], // стили модуля
+        moduleVersion: '1.0.0', // версия модуля
+        appName: 'moduleSourceAppName', // имя приложения, которое является источником модуля
+        mountMode: 'embedded', // режим монтирования модуля
+        moduleRunParams: { // параметры, которые будут доступны при инициализации модуля
+            baseUrl: 'http://localhost:8081',
+        },
+    }),
+});
+```
 
-### (Опционально) Настроить общие библиотеки
-В случае, если модуль который вы хотите подключить использует какие-то общие библиотеки с хост-приложением, вы должны
-определить параметры для этих библиотек в `arui-scripts.config.ts`.
+Вам вовсе не обязательно руками описывать функцию `getModuleResources`. В зависимости от типа модуля, вы можете
+использовать один из готовых хелперов:
 
+Для клиентских модулей:
 ```ts
-import { PackageSettings } from 'arui-scripts';
+import { createModuleLoader, createClientResourcesFetcher } from '@alfalab/scripts-modules';
 
-const aruiScriptsConfig: PackageSettings = {
-    embeddedModules: {
-        shared: {
-            'react': 'reactDOM',
-            'react-dom': 'reactDOM',
-        }
-    },
-    mfModules: {
-        shared: {
-            'react': {
-                eager: true,
-                singleton: true,
-                requiredVersion: '^17.0.0',
-            },
-            'react-dom': {
-                eager: true,
-                singleton: true,
-                requiredVersion: '^17.0.0',
-            }
-        }
-    },
-}
+const loader = createModuleLoader({
+    moduleId: 'test',
+    getModuleResources: createClientResourcesFetcher({
+        baseUrl: 'http://localhost:8081',
+        mountMode: 'mf',
+    }),
+});
 ```
 
-### Подключить модуль на страницу
-Клиентские и серверные модули подключаются на страницу немного по-разному.
+`createClientResourcesFetcher` сам сделает запрос за манифестом приложения, и правильным образом сформирует описание модуля.
 
-Подключение серверных модулей будет выглядеть так:
+Для серверных модулей:
+```ts
+import { createModuleLoader, createServerResourcesFetcher } from '@alfalab/scripts-modules';
+
+const loader = createModuleLoader({
+    moduleId: 'test',
+    getModuleResources: createServerResourcesFetcher({
+        baseUrl: 'http://localhost:8081',
+        headers: { 'X-Auth': 'bla-bla' } // опционально вы можете передать дополнительные заголовки для запроса
+    }),
+});
+```
 
-```tsx
-import React, { useMemo } from 'react';
-import { createLoader, useModuleLoader, getModuleResourcesPath } from '@alfalab/scripts-modules';
-
-// Это просто функция, которая должна обратиться к серверу модуля.
-// Скорее всего у вас уже есть хелпер, который создает подобные функции
-// и насыщает запрос дополнительными данными, например, токеном авторизации, traceId и т.д.
-const customFetch = (loaderParams) => {
-    // arui-scripts не знает заранее ни дополнительных параметров (авторизация, заголовки), которые вы хотите передать в запрос,
-    // ни того, на какой адрес нужно делать запрос. Поэтому вам нужно самим реализовать эту функцию.
-    return fetch(`http://localhost:8081/${getModuleResourcesPath}`, {
-        method: 'POST',
-        body: JSON.stringify(loaderParams),
-        headers: {
-            'Content-Type': 'application/json',
-        },
-    }).then((response) => response.json());
-}
+`createServerResourcesFetcher` сам сделает запрос к ручке, которая отдает описание модуля.
 
-export const ServerModuleMounter = () => {
-    // Загрузчик - это функция, которая прячет в себе запрос к серверу, подключение ресурсов на страницу и т.д.
-    const loader = useMemo(() => createLoader({
-        hostAppId: 'example', // id вашего хост-приложения
-        fetchFunction: customFetch,
-        // С помощью этой функции вы можете передать дополнительные параметры в запрос к серверу модуля.
-        getModuleRequestParams: async () => ({
-            paramName: 'some param that will be passed to module',
-        }),
-    }), []);
-
-    // useModuleLoader - это простой хук, который с помощью переданного загрузчика подключает модуль на страницу.
-    const {
-        loadingState, // состояние загрузки модуля. 'pending' - модуль еще не загружен, 'resolved' - модуль загружен, 'rejected' - произошла ошибка при загрузке модуля
-        targetElementRef, // ссылка на элемент, в который будет подключен модуль
-    } = useModuleLoader(
-        "ServerModuleEmbedded", // id модуля, который был указан в arui-scripts.config.ts
-        loader,
-    );
+В случае же совсем кастомных требований, вы можете реализовать функцию `getModuleResources` самостоятельно.
 
-    return (
-        <div>
-            { loadingState === 'pending' && <div>Loading...</div> }
-            { loadingState === 'rejected' && <div>Failed to load module</div> }
+## Использование загрузчика
+После того как вы создали `loader` - вы легко можете получить доступ к модулю:
 
-            <div ref={ targetElementRef } />
-        </div>
-    );
-};
+```ts
+const { module, unmount, moduleResources } = await loader({
+    getResourcesParams: {}, // параметры, которые будут переданы в getModuleResources
+});
+
+console.log(module); // модуль, который вы загрузили. Тут будут доступны всё, что было экспортировано из модуля
+console.log(moduleResources); // полный ответ от getModuleResources
+
+// вызов этой функции отмонтирует модуль из вашего приложения - удалит скрипты и стили модуля, а так же удалит
+// все глобальные переменные, которые были определены в модуле.
+unmount();
 ```
 
-При подключении же клиентских модулей необходимо использовать функцию `createClientLoader` вместо `createLoader`:
+При вызове `loader` вы можете передать параметры, которые попадут в функцию `getModuleResources`. Это может быть полезно,
+если вы хотите передать какие-то параметры на сервер модуля.
+
+`getModuleResources` будет вызвана со следующими параметрами:
+```ts
+const getModuleResourcesParams = {
+    moduleId: 'test', // id модуля, который вы хотите подключить
+    hostAppId: 'hostAppId', // id вашего приложения
+    params: {}, // параметры, которые вы передали в loader как `getResourcesParams`
+}
+```
+
+На сервер будут отправлены именно эти параметры, они будут доступны как параметр в `getRunParams` в описании вашего модуля.
+
+При использовании клиентских модулей, вам не нужно беспокоиться о том, какие параметры вы передаете в `getModuleResources` - они
+никак не используются в клиентских модулях.
+
+## Использования загрузчика в реакт-приложении
+
+Для того чтобы упростить работу с загрузчиком в реакт-приложении, мы предоставляем хук `useModuleLoader`:
 
 ```tsx
-import React from 'react';
-import { createClientLoader, useModuleLoader } from '@alfalab/scripts-modules';
-import { Underlay } from '@alfalab/core-components/underlay';
-import { Spinner } from '@alfalab/core-components/spinner';
+import { createModuleLoader, useModuleLoader } from '@alfalab/scripts-modules';
 
-const loader = createClientLoader({
-    baseUrl: 'http://localhost:8081/', // базовый адрес приложения с подключаемым модулем
+const loader = createModuleLoader({
+    moduleId: 'test',
+    getModuleResources: createClientResourcesFetcher({
+        baseUrl: 'http://localhost:8081',
+        mountMode: 'mf',
+    }),
 });
 
-export const EmbeddedModuleMounter = () => {
-    const { loadingState, targetElementRef } = useModuleLoader(
-        "ClientModuleEmbedded", // id модуля, который был указан в arui-scripts.config.ts
-        loader
-    );
+const MyComponent = () => {
+    const { loadingState, module, resources } = useModuleLoader(loader); // вторым параметром можно передать параметры, которые будут переданы в getModuleResources
 
     return (
         <div>
-            { loadingState === 'pending' && <Spinner size='m' /> }
-            { loadingState === 'rejected' && <div>Failed to load module</div> }
-
-            <div ref={ targetElementRef } />
+            {loadingState === 'loading' && <div>Loading...</div>}
+            {loadingState === 'error' && <div>Error</div>}
+            {loadingState === 'success' && (
+                <div>
+                    <div>Module loaded</div>
+                    <div>{module}</div> {/* модуль, который вы загрузили. Тут будет доступно всё, что было экспортировано из модуля */}
+                    <div>{resources}</div>
+                </div>
+            )}
         </div>
     );
-}
-
+};
 ```
 
+### Использование монтируемых модулей
 
-# Конфигурация модулей
+Для работы с монтируемыми модулями так же есть готовый хук `useModuleMounter`:
 
-## Embedded модули
-
-`embeddedModules` - объект, управляющий конфигурацией embedded модулей.
-
-- `embeddedModules.shared` - объект, описывающий библиотеки, которые приложение будет предоставлять модулям. Ключ объекта - название библиотеки,
-значение - название переменной в window, в которую будет записана библиотека.
-- `embeddedModules.exposes` - объект, описывающий embedded модули. Ключ объекта - id модуля, значение - объект с конфигурацией модуля.
-- `embeddedModules.exposes[id].entry` - путь до точки входа модуля. Должен быть либо абсолютным, либо относительным от корня проекта.
-- `embeddedModules.exposes[id].cssPrefix` - префикс для css классов модуля. По умолчанию все стили модуля будут префиксированы с `.module-{id модуля}`. Вы можете передать сюда
-свой префикс, или `false` чтобы отключить префиксирование.
-- `embeddedModules.exposes[id].embeddedConfig` - объект, описывающий какие библиотеки должны быть помечены для модуля как `external`. Ключ объекта - название библиотеки,
-значение - название переменной в window, в которой модуль будет искать эту библиотеку.
-
-## MF модули
+```tsx
+import { createModuleLoader, useModuleMounter } from '@alfalab/scripts-modules';
 
-`mfModules` - объект, управляющий конфигурацией Module Federation модулей.
+const loader = createModuleLoader({
+    moduleId: 'test',
+    getModuleResources: createClientResourcesFetcher({
+        baseUrl: 'http://localhost:8081',
+        mountMode: 'embedded',
+    }),
+});
 
-- `mfModules.name` - опциональное имя модуля. Это имя будет использовано как название контейнера модуля. Если не указано, то
-будет использовано имя пакета, в котором все `-` будут заменены на `_`. Должно быть уникальным в рамках хост-приложения,
-и быть валидным именем для js переменной.
-- `mfModules.shared` - объект, описывающий библиотеки, которые приложение будет предоставлять модулям, и библиотеки, которые модуль будет пытаться получить от хост-приложения.
-Подробнее про варианты описания можно почитать в [документации](https://webpack.js.org/plugins/module-federation-plugin/#specify-package-versions).
-- `exposes` - объект, описывающий какие модули должны быть предоставлены хост-приложению. Ключ объекта - название модуля,
-значение - точка входа модуля.
+const MyComponent = () => {
+    const { loadingState, targetElementRef } = useModuleMounter({
+        loader,
+        loaderParams: {}, // параметры, которые будут переданы в getModuleResources, опционально
+        runParams: {}, // параметры, которые будут переданы в mount функцию модуля, опционально
+    });
 
-# API библиотек
+    return (
+        <div>
+            {loadingState === 'loading' && <div>Loading...</div>}
+            {loadingState === 'error' && <div>Error</div>}
+            <div ref={targetElementRef} /> {/* сюда будет монтироваться модуль */}
+        </div>
+    );
+};
+```

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "arui-scripts",
-    "version": "14.5.0-feat-modules.2",
+    "version": "14.5.0-feat-modules.3",
     "main": "./build/index.js",
     "typings": "./build/index.d.ts",
     "license": "MPL-2.0",