arui-scripts 0.0.0-client-only-envs-20250408153713

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.
Files changed (222) hide show
  1. package/.browserslistrc +5 -0
  2. package/.eslintignore +2 -0
  3. package/.eslintrc.js +17 -0
  4. package/.turbo/turbo-build.log +0 -0
  5. package/.turbo/turbo-test.log +23 -0
  6. package/CHANGELOG.md +1571 -0
  7. package/README.md +47 -0
  8. package/bin/build.sh +2 -0
  9. package/build/bin/index.d.ts +3 -0
  10. package/build/bin/index.js +29 -0
  11. package/build/commands/archive-build/index.d.ts +1 -0
  12. package/build/commands/archive-build/index.js +80 -0
  13. package/build/commands/build/build-wrapper.d.ts +8 -0
  14. package/build/commands/build/build-wrapper.js +42 -0
  15. package/build/commands/build/client.d.ts +1 -0
  16. package/build/commands/build/client.js +41 -0
  17. package/build/commands/build/index.d.ts +1 -0
  18. package/build/commands/build/index.js +15 -0
  19. package/build/commands/build/server.d.ts +1 -0
  20. package/build/commands/build/server.js +29 -0
  21. package/build/commands/bundle-analyze/index.d.ts +1 -0
  22. package/build/commands/bundle-analyze/index.js +40 -0
  23. package/build/commands/changelog/index.d.ts +5 -0
  24. package/build/commands/changelog/index.js +113 -0
  25. package/build/commands/docker-build/index.d.ts +1 -0
  26. package/build/commands/docker-build/index.js +73 -0
  27. package/build/commands/docker-build-compiled/index.d.ts +1 -0
  28. package/build/commands/docker-build-compiled/index.js +54 -0
  29. package/build/commands/ensure-yarn/index.d.ts +0 -0
  30. package/build/commands/ensure-yarn/index.js +8 -0
  31. package/build/commands/start/client.d.ts +1 -0
  32. package/build/commands/start/client.js +8 -0
  33. package/build/commands/start/index.d.ts +1 -0
  34. package/build/commands/start/index.js +17 -0
  35. package/build/commands/start/print-compiler-output.d.ts +1 -0
  36. package/build/commands/start/print-compiler-output.js +16 -0
  37. package/build/commands/start/server.d.ts +1 -0
  38. package/build/commands/start/server.js +8 -0
  39. package/build/commands/start-prod/client.d.ts +1 -0
  40. package/build/commands/start-prod/client.js +8 -0
  41. package/build/commands/start-prod/index.d.ts +1 -0
  42. package/build/commands/start-prod/index.js +17 -0
  43. package/build/commands/start-prod/server.d.ts +1 -0
  44. package/build/commands/start-prod/server.js +8 -0
  45. package/build/commands/test/get-config.d.ts +1 -0
  46. package/build/commands/test/get-config.js +104 -0
  47. package/build/commands/test/index.d.ts +1 -0
  48. package/build/commands/test/index.js +60 -0
  49. package/build/commands/util/client-assets-sizes.d.ts +26 -0
  50. package/build/commands/util/client-assets-sizes.js +82 -0
  51. package/build/commands/util/docker-build.d.ts +23 -0
  52. package/build/commands/util/docker-build.js +127 -0
  53. package/build/commands/util/exec.d.ts +2 -0
  54. package/build/commands/util/exec.js +20 -0
  55. package/build/commands/util/format-webpack-messages.d.ts +11 -0
  56. package/build/commands/util/format-webpack-messages.js +95 -0
  57. package/build/commands/util/make-tmp-dir.d.ts +6 -0
  58. package/build/commands/util/make-tmp-dir.js +29 -0
  59. package/build/commands/util/run-client-dev-server.d.ts +2 -0
  60. package/build/commands/util/run-client-dev-server.js +46 -0
  61. package/build/commands/util/run-compilers.d.ts +1 -0
  62. package/build/commands/util/run-compilers.js +37 -0
  63. package/build/commands/util/run-server-watch-compiler.d.ts +2 -0
  64. package/build/commands/util/run-server-watch-compiler.js +19 -0
  65. package/build/commands/util/tsc.d.ts +1 -0
  66. package/build/commands/util/tsc.js +13 -0
  67. package/build/commands/util/yarn.d.ts +5 -0
  68. package/build/commands/util/yarn.js +55 -0
  69. package/build/configs/app-configs/calculate-dependent-config.d.ts +9 -0
  70. package/build/configs/app-configs/calculate-dependent-config.js +38 -0
  71. package/build/configs/app-configs/get-defaults.d.ts +5 -0
  72. package/build/configs/app-configs/get-defaults.js +139 -0
  73. package/build/configs/app-configs/index.d.ts +6 -0
  74. package/build/configs/app-configs/index.js +24 -0
  75. package/build/configs/app-configs/read-config-file.d.ts +2 -0
  76. package/build/configs/app-configs/read-config-file.js +28 -0
  77. package/build/configs/app-configs/types.d.ts +126 -0
  78. package/build/configs/app-configs/types.js +2 -0
  79. package/build/configs/app-configs/update-with-config-file.d.ts +2 -0
  80. package/build/configs/app-configs/update-with-config-file.js +17 -0
  81. package/build/configs/app-configs/update-with-env.d.ts +2 -0
  82. package/build/configs/app-configs/update-with-env.js +23 -0
  83. package/build/configs/app-configs/update-with-package.d.ts +2 -0
  84. package/build/configs/app-configs/update-with-package.js +13 -0
  85. package/build/configs/app-configs/update-with-presets.d.ts +3 -0
  86. package/build/configs/app-configs/update-with-presets.js +41 -0
  87. package/build/configs/app-configs/validate-settings-keys.d.ts +4 -0
  88. package/build/configs/app-configs/validate-settings-keys.js +13 -0
  89. package/build/configs/app-configs/warn-about-deprecations.d.ts +2 -0
  90. package/build/configs/app-configs/warn-about-deprecations.js +20 -0
  91. package/build/configs/babel-client.d.ts +32 -0
  92. package/build/configs/babel-client.js +72 -0
  93. package/build/configs/babel-dependencies.d.ts +14 -0
  94. package/build/configs/babel-dependencies.js +39 -0
  95. package/build/configs/babel-server.d.ts +27 -0
  96. package/build/configs/babel-server.js +48 -0
  97. package/build/configs/client-env-config/add-env-to-html-template.d.ts +1 -0
  98. package/build/configs/client-env-config/add-env-to-html-template.js +7 -0
  99. package/build/configs/client-env-config/client-config-plugin.d.ts +5 -0
  100. package/build/configs/client-env-config/client-config-plugin.js +26 -0
  101. package/build/configs/client-env-config/constants.d.ts +1 -0
  102. package/build/configs/client-env-config/constants.js +4 -0
  103. package/build/configs/client-env-config/get-env-config.d.ts +2 -0
  104. package/build/configs/client-env-config/get-env-config.js +28 -0
  105. package/build/configs/client-env-config/index.d.ts +3 -0
  106. package/build/configs/client-env-config/index.js +9 -0
  107. package/build/configs/config-extras/minimizers/imagemin/imagemin.d.ts +28 -0
  108. package/build/configs/config-extras/minimizers/imagemin/imagemin.js +65 -0
  109. package/build/configs/config-extras/minimizers/imagemin/index.d.ts +1 -0
  110. package/build/configs/config-extras/minimizers/imagemin/index.js +17 -0
  111. package/build/configs/config-extras/minimizers/index.d.ts +1 -0
  112. package/build/configs/config-extras/minimizers/index.js +17 -0
  113. package/build/configs/dev-server.d.ts +2 -0
  114. package/build/configs/dev-server.js +73 -0
  115. package/build/configs/jest/babel-transform.d.ts +2 -0
  116. package/build/configs/jest/babel-transform.js +6 -0
  117. package/build/configs/jest/css-mock.d.ts +1 -0
  118. package/build/configs/jest/css-mock.js +2 -0
  119. package/build/configs/jest/file-transform.d.ts +3 -0
  120. package/build/configs/jest/file-transform.js +11 -0
  121. package/build/configs/jest/settings.d.ts +21 -0
  122. package/build/configs/jest/settings.js +58 -0
  123. package/build/configs/modules.d.ts +16 -0
  124. package/build/configs/modules.js +149 -0
  125. package/build/configs/mq.css +22 -0
  126. package/build/configs/postcss.config.d.ts +36 -0
  127. package/build/configs/postcss.config.js +71 -0
  128. package/build/configs/postcss.d.ts +2 -0
  129. package/build/configs/postcss.js +11 -0
  130. package/build/configs/process-assets-plugin-output.d.ts +2 -0
  131. package/build/configs/process-assets-plugin-output.js +45 -0
  132. package/build/configs/server-externals-exemptions.d.ts +1 -0
  133. package/build/configs/server-externals-exemptions.js +21 -0
  134. package/build/configs/stats-options.d.ts +3 -0
  135. package/build/configs/stats-options.js +49 -0
  136. package/build/configs/supporting-browsers.d.ts +2 -0
  137. package/build/configs/supporting-browsers.js +8 -0
  138. package/build/configs/swc.d.ts +4 -0
  139. package/build/configs/swc.js +35 -0
  140. package/build/configs/util/apply-overrides.d.ts +76 -0
  141. package/build/configs/util/apply-overrides.js +52 -0
  142. package/build/configs/util/check-node-version.d.ts +2 -0
  143. package/build/configs/util/check-node-version.js +7 -0
  144. package/build/configs/util/find-loader.d.ts +2 -0
  145. package/build/configs/util/find-loader.js +24 -0
  146. package/build/configs/util/find-plugin.d.ts +85 -0
  147. package/build/configs/util/find-plugin.js +22 -0
  148. package/build/configs/util/get-entry.d.ts +9 -0
  149. package/build/configs/util/get-entry.js +22 -0
  150. package/build/configs/util/get-polyfills.d.ts +2 -0
  151. package/build/configs/util/get-polyfills.js +26 -0
  152. package/build/configs/util/get-webpack-cache-dependencies.d.ts +1 -0
  153. package/build/configs/util/get-webpack-cache-dependencies.js +18 -0
  154. package/build/configs/util/install-sourcemap-support.d.ts +1 -0
  155. package/build/configs/util/install-sourcemap-support.js +11 -0
  156. package/build/configs/util/node-assets-ignore.d.ts +0 -0
  157. package/build/configs/util/node-assets-ignore.js +33 -0
  158. package/build/configs/util/noop.d.ts +1 -0
  159. package/build/configs/util/noop.js +2 -0
  160. package/build/configs/util/register-ts-node.d.ts +0 -0
  161. package/build/configs/util/register-ts-node.js +18 -0
  162. package/build/configs/util/resolve.d.ts +12 -0
  163. package/build/configs/util/resolve.js +29 -0
  164. package/build/configs/webpack.client.d.ts +10 -0
  165. package/build/configs/webpack.client.dev.d.ts +2 -0
  166. package/build/configs/webpack.client.dev.js +15 -0
  167. package/build/configs/webpack.client.js +475 -0
  168. package/build/configs/webpack.client.prod.d.ts +2 -0
  169. package/build/configs/webpack.client.prod.js +15 -0
  170. package/build/configs/webpack.server.d.ts +2 -0
  171. package/build/configs/webpack.server.dev.d.ts +2 -0
  172. package/build/configs/webpack.server.dev.js +11 -0
  173. package/build/configs/webpack.server.js +256 -0
  174. package/build/configs/webpack.server.prod.d.ts +2 -0
  175. package/build/configs/webpack.server.prod.js +11 -0
  176. package/build/index.d.ts +5 -0
  177. package/build/index.js +9 -0
  178. package/build/plugins/arui-runtime/arui-runtime-module.d.ts +7 -0
  179. package/build/plugins/arui-runtime/arui-runtime-module.js +20 -0
  180. package/build/plugins/arui-runtime/index.d.ts +11 -0
  181. package/build/plugins/arui-runtime/index.js +47 -0
  182. package/build/plugins/postcss-global-variables/postcss-global-variables.d.ts +6 -0
  183. package/build/plugins/postcss-global-variables/postcss-global-variables.js +38 -0
  184. package/build/plugins/postcss-global-variables/utils/utils.d.ts +7 -0
  185. package/build/plugins/postcss-global-variables/utils/utils.js +91 -0
  186. package/build/plugins/postcss-prefix-selector.d.ts +6 -0
  187. package/build/plugins/postcss-prefix-selector.js +62 -0
  188. package/build/plugins/reload-server-plugin.d.ts +10 -0
  189. package/build/plugins/reload-server-plugin.js +44 -0
  190. package/build/plugins/turn-off-split-remote-entry.d.ts +11 -0
  191. package/build/plugins/turn-off-split-remote-entry.js +71 -0
  192. package/build/plugins/watch-missing-node-modules-plugin.d.ts +6 -0
  193. package/build/plugins/watch-missing-node-modules-plugin.js +20 -0
  194. package/build/templates/base-nginx.conf.template.d.ts +2 -0
  195. package/build/templates/base-nginx.conf.template.js +61 -0
  196. package/build/templates/dockerfile-compiled.template.d.ts +2 -0
  197. package/build/templates/dockerfile-compiled.template.js +52 -0
  198. package/build/templates/dockerfile.template.d.ts +2 -0
  199. package/build/templates/dockerfile.template.js +41 -0
  200. package/build/templates/html.template.d.ts +1 -0
  201. package/build/templates/html.template.js +25 -0
  202. package/build/templates/nginx.conf.template.d.ts +2 -0
  203. package/build/templates/nginx.conf.template.js +39 -0
  204. package/build/templates/start.template.d.ts +2 -0
  205. package/build/templates/start.template.js +69 -0
  206. package/build/tsconfig-local.tsbuildinfo +1 -0
  207. package/docs/artifact.md +58 -0
  208. package/docs/caveats.md +41 -0
  209. package/docs/client-only.md +77 -0
  210. package/docs/commands.md +125 -0
  211. package/docs/compilers.md +18 -0
  212. package/docs/examples.md +100 -0
  213. package/docs/modules.md +780 -0
  214. package/docs/overrides.md +167 -0
  215. package/docs/presets.md +65 -0
  216. package/docs/settings.md +287 -0
  217. package/jest-preset.js +5 -0
  218. package/package.json +180 -0
  219. package/stylelint.config.js +11 -0
  220. package/tsconfig-local.json +16 -0
  221. package/tsconfig.eslint.json +5 -0
  222. package/tsconfig.json +71 -0
@@ -0,0 +1,780 @@
1
+ # Что такое модули
2
+ Модули приложений предназначены для решения простой проблемы - переиспользование фронтового кода между приложениями.
3
+
4
+ В целом, для того чтобы переиспользовать код у нас есть много разных способов, например:
5
+ - копировать код из одного приложения в другое. Быстро, но неудобно и неэффективно.
6
+ - выносить код в отдельный пакет и подключать его через npm. Понятный и достаточно удобный вариант,
7
+ но ограничивает нас в скорости изменений. Если мы хотим заменить обновить код в пакете, процесс
8
+ раскатки этого обновления на все приложения может занять много времени.
9
+ - Сделать так, чтобы мы могли подключать код из других приложений в свое. При этом мы получаем
10
+ возможность быстро изменить общий код только в одном месте, а все приложения автоматически получат
11
+ обновления.
12
+
13
+ Модули позволяют реализовать именно последний вариант. Если вы знакомы с концепцией [module federation](https://webpack.js.org/concepts/module-federation/),
14
+ то модули приложений - это его реализация в рамках arui-scripts, с дополнительным уровнем абстракции, который, в том числе,
15
+ позволяет использовать модули без самого module-federation.
16
+
17
+ # Как использовать
18
+
19
+ Предположим у вас есть два приложения, `foo-app` и `bar-app`. Вы хотите предоставлять модуль из `foo-app` и использовать
20
+ его в `bar-app`.
21
+
22
+ ## 1. Добавляем конфигурацию в arui-scripts.config.ts (в foo-app)
23
+
24
+ ```ts
25
+ // ./arui-scripts.config.ts
26
+ import type { PackageSettings } from 'arui-scripts';
27
+
28
+ const aruiScriptsConfig: PackageSettings = {
29
+ modules: {
30
+ // если хост приложение шарит эти библиотеки, и они совпадают по версии
31
+ shared: {
32
+ 'react': '^17.0.0', // так же поддерживаются более сложные версии например { requiredVersion: '^17.0.0', singleton: true }
33
+ 'react-dom': '^17.0.0',
34
+ },
35
+ exposes: {
36
+ 'SomeModule': './src/modules/some-module/index',
37
+ 'AnotherModule': './src/modules/another-module/index',
38
+ }
39
+ }
40
+ }
41
+
42
+ export default aruiScriptsConfig;
43
+ ```
44
+
45
+ Эта конфигурация объявляет два модуля, `SomeModule` и `AnotherModule`. Эти модули смогут получать react и react-dom из
46
+ подключившего их приложения, если оно содержит конфигурацию для `modules.shared`, и версии библиотек подходят по semver.
47
+
48
+ ## 2. Создаем входную точку модуля (в foo-app)
49
+
50
+ ```tsx
51
+ // src/modules/some-module/index
52
+ import type { ModuleMountFunction, ModuleUnmountFunction } from '@alfalab/scripts-modules';
53
+ export const mount: ModuleMountFunction = (targetNode, runParams, serverState) => {
54
+ console.log( // Вы можете передать эти переменные в ваши компоненты, подробнее ниже
55
+ runParams, // undefined
56
+ serverState // { baseUrl: "https://example.com/foo-app", hostAppId: "bar-app" } // Эти данные определяются тем, что было передано в загрузчик в приложении-хосте
57
+ );
58
+
59
+ ReactDOM.render(
60
+ <div>Hello from module!</div>,
61
+ targetNode,
62
+ );
63
+ }
64
+
65
+ export const unmount: ModuleUnmountFunction = (targetNode) => {
66
+ ReactDOM.unmountComponentAtNode(targetNode);
67
+ }
68
+ ```
69
+
70
+ Пример для React@18
71
+
72
+ ```tsx
73
+ import type { ModuleMountFunction, ModuleUnmountFunction } from '@alfalab/scripts-modules';
74
+ import ReactDOM from 'react-dom';
75
+
76
+ let root: ReturnType<typeof ReactDOM.createRoot>
77
+
78
+ export const mount: ModuleMountFunction = (targetNide, runParams, serverState) => {
79
+ root = ReactDOM.createRoot(targetNode);
80
+
81
+ root.render(<App preparedState={serverState} runParams={runParams} />);
82
+ }
83
+
84
+ export const unmount: ModuleUnmountFunction = () => {
85
+ root?.unmount();
86
+ }
87
+ ```
88
+
89
+ ## 3. Подключите модуль в другом приложении (в bar-app)
90
+
91
+ Если предположить что приложение с модулем уже развернуто по адресу https://examle.com/foo-app
92
+ ```tsx
93
+ import {
94
+ createModuleLoader,
95
+ createModuleFetcher,
96
+ useModuleMounter,
97
+ MountableModule,
98
+ } from '@alfalab/scripts-modules';
99
+
100
+ const loader = createModuleLoader<MountableModule>({
101
+ hostAppId: 'bar-app',
102
+ moduleId: 'test',
103
+ getModuleResources: createModuleFetcher({
104
+ baseUrl: 'https://examle.com/foo-app',
105
+ }),
106
+ });
107
+
108
+ export const MyAwesomeComponent = () => {
109
+ const { loadingState, targetElementRef } = useModuleMounter({ loader });
110
+
111
+ return (
112
+ <div>
113
+ {loadingState === 'pending' && <div>pending...</div>}
114
+ {loadingState === 'rejected' && <div>Error</div>}
115
+ <div ref={targetElementRef} /> {/* сюда будет монтироваться модуль */}
116
+ </div>
117
+ );
118
+ }
119
+ ```
120
+
121
+ На этом этапе вы получите подгружающееся в bar-app модуль.
122
+
123
+ ## 4. (Опционально). Определить shared-библиотеки в приложении потребителе (в bar-app)
124
+
125
+ ```ts
126
+ // ./arui-scripts.config.ts
127
+ import type { PackageSettings } from 'arui-scripts';
128
+
129
+ const aruiScriptsConfig: PackageSettings = {
130
+ modules: {
131
+ shared: {
132
+ 'react': '^17.0.0',
133
+ 'react-dom': '^17.0.0',
134
+ },
135
+ }
136
+ }
137
+
138
+ export default aruiScriptsConfig;
139
+ ```
140
+ Эта конфигурация даст возможность использовать react и react-dom библиотеки из bar-app, не загружая их из foo-app.
141
+
142
+ ## Готово!
143
+
144
+ Эта минимальная конфигурация, которая нужна для работы с модулями. Далее идет информация об advanced настройках работы с модулями.
145
+ Рекомендуется с ней ознакомиться хотя бы верхнеуровнево, для того, чтобы понимать какие возможности есть у модулей.
146
+
147
+ # Передача параметров в модуль из приложения-потребителя
148
+ Зачастую модули должны получать какую-то информацию из приложения потребителя при своей инициализации.
149
+
150
+ На стороне модуля эти параметры приходят в параметр `runParams` функции mount. Предположим ваш модуль должен получать из
151
+ приложения-потребителя тему (`theme`) и ширину (`width`). Тогда входная точка будет выглядеть примерно так:
152
+
153
+ ```tsx
154
+ import type { ModuleMountFunction, ModuleUnmountFunction } from '@alfalab/scripts-modules';
155
+
156
+ type ModuleRunParams = {
157
+ theme: stirng;
158
+ width: number;
159
+ };
160
+
161
+ export const mount: ModuleMountFunction<ModuleRunParams> = (targetNode, runParams) => {
162
+ ReactDOM.render(
163
+ <MyAwesomeComponent theme={runParams.theme} width={runParams.width} />,
164
+ targetNode,
165
+ );
166
+ }
167
+ // далее unmount как и раньше
168
+ ```
169
+
170
+ На стороне потребителя:
171
+
172
+ ```tsx
173
+ import { createModuleLoader, MountableModule, useModuleMounter } from '@alfalab/scripts-modules';
174
+
175
+ // У нас возможности передать типы из приложения-модуля в приложение-хост
176
+ // При желании вы можете вынести эти типы в общую библиотеку и использовать оттуда
177
+ type ModuleRunParams = {
178
+ theme: string;
179
+ width: number;
180
+ };
181
+
182
+ type ModuleType = MountableModule<ModuleRunParams>;
183
+
184
+ const loader = createModuleLoader<ModuleType>(/*...*/);
185
+ export const MyAwesomeComponent = () => {
186
+ const { loadingState, targetElementRef } = useModuleMounter({
187
+ loader,
188
+ runParams: { theme: 'blue', width: 300 },
189
+ });
190
+
191
+ return (
192
+ <div>
193
+ { loadingState === 'pending' && <div>pending...</div> }
194
+ { loadingState === 'rejected' && <div>Error</div> }
195
+ <div ref={ targetElementRef }/>
196
+ </div>
197
+ );
198
+ }
199
+ ```
200
+
201
+ :warning: **Внимание!** Модуль не будет обновляться при изменении runParams. Это осознанное решение, вы не должны относится к
202
+ параметрам тут с той же легкостью, что и к prop-ам react-компонентов. Очень легко провести параллели между эти двумя
203
+ концепциями, но использование runParams специально сделано менее удобным - чем меньше вы их используете, тем реже вы будете
204
+ их менять, и тем меньше вероятность привнести обратно несовместимые изменения. Старайтесь передавать в runParams только
205
+ примитивы, не пытаться передавать там объекты сущностей (например профиль пользователя).
206
+ В целом - минимизируйте их использование.
207
+ Если вам важно чтобы модуль перемонтировался каждый раз при изменении runParams - вы можете сделать это самостоятельно, например добавив
208
+ key в ваш компонент-обертку вокруг модуля.
209
+
210
+ # Возможность управления модулями с сервера
211
+ Сами модули используются только на клиентской части приложения. Но, в некоторых случаях, может быть полезно иметь возможность
212
+ управлять тем, какой модуль должен быть подключен на странице с сервера, или же иметь модуль, который будет при загрузке
213
+ иметь доступ к данным, доступным только на сервере (аналогично тому, как мы передаем серверный стейт в приложения при SSR).
214
+
215
+ По умолчанию, даже в клиентские модули в mount-функцию будет передан параметр `serverState`, содержащий:
216
+ - `baseUrl` - тот адрес, который использовался при загрузке модуля с помощью `createModuleFetcher`. Вы можете использовать
217
+ этот адрес например для определения того, где искать API вашего модуля
218
+ - `hostAppId` - идентификатор приложения, которое загружает модуль. Может быть полезен если вы хотите менять поведение
219
+ модуля в зависимости от того, кто его потребляет.
220
+
221
+ Так же `arui-scripts` предоставляет возможность создать специальный эндпоинт на вашем сервере, из которого вы сможете управлять
222
+ состоянием модуля.
223
+
224
+ Модули с такой возможностью мы называем _модулями с серверным состоянием_ (_server state_).
225
+
226
+ Для удобного создания таких эндпоинтов сделаны хелперы в пакете `@alfalab/scripts-server`. Например, для `hapi@20`:
227
+
228
+ ```ts
229
+ import { createGetModulesHapi20Plugin } from '@alfalab/scripts-server/build/hapi-20';
230
+
231
+ const plugin = createGetModulesHapi20Plugin(
232
+ {
233
+ 'SomeModule': {
234
+ mountMode: 'default',
235
+ version: '1.0.0',
236
+ getModuleState: async (getResourcesRequest, request) => {
237
+ console.log(getResourcesRequest.moduleId); // "SomeModule"
238
+ console.log(getResourcesRequest.hostAppId); // В зависимости от того, что за приложение запросило модуль
239
+ console.log(getResourcesRequest.params); // параметры запроса за модулем, подробнее ниже
240
+ console.log(request); // Для каждого фреймворка это будет специфичный для него объект запроса
241
+ const answerFromAwesomeService = await getSomethingFromBackend();
242
+ return {
243
+ baseUrl: '/awesome-app',
244
+ answerFromAwesomeService, // эти данные попадут в параметр serverState mount-функции модуля
245
+ };
246
+ },
247
+ }
248
+ }
249
+ );
250
+
251
+ server.register(plugin);
252
+ ```
253
+
254
+ Для других фреймворков это будет выглядеть аналогично, для `express`
255
+ ```ts
256
+ import { createGetModulesExpress } from '@alfalab/scripts-server/build/express';
257
+
258
+ const modulesRouter = createGetModulesExpress({/*...*/});
259
+
260
+ app.use(modulesRouter);
261
+ ```
262
+
263
+ Для `hapi@16`:
264
+
265
+ ```ts
266
+ import { createGetModulesHapi16Plugin } from '@alfalab/scripts-server/build/hapi16';
267
+
268
+ const modulesPlugin = createGetModulesHapi16Plugin({/*...*/});
269
+
270
+ server.register(modulesPlugin);
271
+ ```
272
+
273
+ Если вы хотите использовать другой серверный фреймворк, вы можете использовать общий хелпер:
274
+
275
+ ```ts
276
+ import { createGetModulesMethod } from '@alfalab/scripts-server';
277
+
278
+ const getModules = createGetModulesMethod({/*...*/});
279
+
280
+ // getModules будет иметь следующую сигнатуру:
281
+ type ModulesMethod = {
282
+ method: string; // http метод, который нужно использовать для обработки запроса
283
+ path: string; // путь, который нужно использовать для обработки запроса
284
+ handler: (request: GetResourcesRequest) => Promise<GetResourcesResponse>; // обработчик запроса
285
+ }
286
+
287
+ // далее в зависимости от фреймворка вы можете использовать этот метод
288
+ // для конфигурации вашего сервера
289
+ // вы можете посмотреть примеры реализации тких методов для express, hapi@16 и hapi@20.
290
+ ```
291
+
292
+ ## Подключение модулей с серверным состоянием в приложении потребителе
293
+ Приложение-потребитель должно знать, что модуль имеет серверное состояние, поскольку это требует
294
+ небольшого изменения механизма подключения модуля:
295
+
296
+ ```tsx
297
+ import {
298
+ createModuleLoader,
299
+ createServerStateModuleFetcher,
300
+ useModuleMounter,
301
+ MountableModule,
302
+ } from '@alfalab/scripts-modules';
303
+
304
+ type RequestParams = { // Опционально, вы можете определить параметры которые попадут на серверную часть модуля, в getResourcesRequest.params
305
+ name: string;
306
+ }
307
+
308
+ const loader = createModuleLoader<MountableModule, RequestParams>({
309
+ hostAppId: 'bar-app',
310
+ moduleId: 'test',
311
+ getModuleResources: createServerStateModuleFetcher({ // !!! другой метод подключения
312
+ baseUrl: 'http://localhost:8082',
313
+ headers: { 'X-Auth': 'bla-bla' } // опционально вы можете передать дополнительные заголовки для запроса
314
+ }),
315
+ });
316
+
317
+ export const MyAwesomeComponent = () => {
318
+ const { loadingState, targetElementRef } = useModuleMounter({
319
+ loader,
320
+ loaderParams: { name: 'Ivan' }, // Если модуль не принимает кастомных параметров на сервере - этого можно не делать!
321
+ });
322
+
323
+ return (
324
+ <div>
325
+ {loadingState === 'pending' && <div>pending...</div>}
326
+ {loadingState === 'rejected' && <div>Error</div>}
327
+ <div ref={targetElementRef} /> {/* сюда будет монтироваться модуль */}
328
+ </div>
329
+ );
330
+ }
331
+ ```
332
+
333
+ # Изоляция стилей
334
+ Если ваши приложения активно используют глобальные стили (то есть не с css-modules или css-in-js), вы вполне
335
+ можете столкнуться с проблемой конфликтов стилей между модулями и приложением-потребителем.
336
+
337
+ Для решения конфликтов стилей вы можете попробовать перевести проект на css-modules, но это может быть довольно
338
+ трудоемкой задачей, особенно если у вас уже есть большая кодовая база.
339
+
340
+ arui-scripts предоставляет два решения для этой проблемы:
341
+ - _css-prefix_
342
+ - использование shadow dom
343
+
344
+ ## css-prefix
345
+
346
+ Суть метода заключается в том, что ко всем стилям модуля будет добавляться префикс, который позволит изолировать
347
+ стили модуля от стилей приложения-потребителя.
348
+
349
+ :warning: **Внимание!** - изоляция стилей работает только в одном направлении - стили модуля не будут применены к элементам
350
+ хост-приложения. Но стили хост-приложения могут быть применены к элементам модуля.
351
+
352
+ Для того чтобы использовать этот метод, вам нужно:
353
+
354
+ 1. Изменить конфигурацию модуля в `arui-scripts.config.ts`:
355
+
356
+ ```ts
357
+ // ./arui-scripts.config.ts compatModules
358
+ import type { PackageSettings } from 'arui-scripts';
359
+
360
+ const aruiScriptsConfig: PackageSettings = {
361
+ compatModules: {
362
+ // Тут ключ - название библиотеки, значение - имя переменной в window, которая будет использоваться для получения библиотеки
363
+ // Это те библиотеки, которые этот проект будет предоставлять модулям, подключаемым в него
364
+ shared: {
365
+ 'react': 'react',
366
+ 'react-dom': 'reactDOM',
367
+ },
368
+ exposes: {
369
+ 'SomeModule': {
370
+ entry: './src/modules/some-module/index',
371
+ // Это те библиотеки, которые модуль будет пытаться получить из window
372
+ externals: {
373
+ react: 'react',
374
+ 'react-dom': 'reactDOM',
375
+ },
376
+ },
377
+ 'AnotherModule': {
378
+ entry: './src/modules/another-module/index',
379
+ },
380
+ }
381
+ }
382
+ }
383
+
384
+ export default aruiScriptsConfig;
385
+ ```
386
+
387
+ ```ts
388
+ // ./arui-scripts.config.ts module federation
389
+ import type { PackageSettings } from 'arui-scripts';
390
+
391
+ const aruiScriptsConfig: PackageSettings = {
392
+ modules: {
393
+ shared: {
394
+ 'react': '^17.0.0',
395
+ 'react-dom': '^17.0.0',
396
+ },
397
+ exposes: {
398
+ 'Module': './src/modules/module/index',
399
+ },
400
+ options: {
401
+ cssPrefix: '.my-module'
402
+ }
403
+ }
404
+ }
405
+
406
+ export default aruiScriptsConfig;
407
+ ```
408
+
409
+ 2. Изменить входную точку модуля:
410
+
411
+ ```tsx
412
+ // ./src/modules/some-module/index
413
+ import type {
414
+ ModuleMountFunction,
415
+ ModuleUnmountFunction,
416
+ WindowWithMountableModule,
417
+ } from '@alfalab/scripts-modules';
418
+
419
+ const CSS_PREFIX = 'module-SomeModule'; // префикс, который будет добавлен к классам модуля. По умолчанию - module-<moduleId>
420
+
421
+ // Если ваше react-приложение использует порталы, вам так же надо не забыть добавить префикс к элементу-порталу.
422
+ export const mount: ModuleMountFunction = (targetNode, runParams, serverState) => {
423
+ ReactDOM.render(
424
+ <div className={ CSS_PREFIX }>Hello from module!</div>,
425
+ targetNode,
426
+ );
427
+ }
428
+
429
+ export const unmount: ModuleUnmountFunction = (targetNode) => {
430
+ ReactDOM.unmountComponentAtNode(targetNode);
431
+ };
432
+
433
+ (window as WindowWithMountableModule).SomeModule = { // имя переменной в window должно соответствовать имени модуля в exposes
434
+ mount: mountModule,
435
+ unmount: unmountModule,
436
+ };
437
+ ```
438
+
439
+ Как видите, изменения в сравнении с обычными модулями минимальны. На стороне потребителя при
440
+ этом не меняется ничего - `@alfalab/script-modules` сам поймет как загружать такой модуль и будет подключать его
441
+ нужным способом.
442
+
443
+ <details>
444
+ <summary>Писать в window? Вы что, с дуба рухнулись?</summary>
445
+ Да, конечно, это может создать определенные проблемы (конфликты имен модулей, определенные ограничения на используемые названия),
446
+ но по сути это единственный способ передать код модуля в хост-приложение.
447
+
448
+ Webpack module federation делает абсолютно то же самое, просто прячет работу с глобальными переменными за собой.
449
+ </details>
450
+
451
+ ### Сравнение способов подключения модулей
452
+
453
+ `default` модули:
454
+ - **+++** Простой способ для переиспользования библиотек между модулем и приложением-хостом.
455
+ - **+++** Возможность использовать разные версии общих библиотек в разных модулях/хостах (речь про те библиотеки, которые будут шарится).
456
+ - **---** Нет встроенной изоляции стилей. Стили модуля будут применены к хост-приложению.
457
+ - **---** Нет возможности использовать модуль в приложении, которое не использует webpack.
458
+
459
+ Проблема изоляции стилей может быть решена с помощью [shadow dom](#shadow-dom),
460
+ или с помощью css modules. Но это накладывает некоторые ограничения либо на поддерживаемые браузеры (shadow dom), либо на
461
+ существующую кодовую базу (css modules должны использоваться везде, если у вас будет две версии arui-feather на странице - будет не очень приятно).
462
+
463
+ `compat` модули:
464
+ - **+++** Встроенная изоляция стилей. Стили модуля не будут применены к хост-приложению, если только вы не захотите этого.
465
+ - **---** Нет возможности использовать разные версии общих библиотек в разных модулях/хостах, если вы хотите их шарить.
466
+
467
+ *Как понять какой режим использовать?*
468
+ В целом, если ваше приложение и модули используют только css-modules, то можно использовать `default` режим. Конфликты в стилях
469
+ вам в таком случае не грозят. Если же вы используете обычный css, или ваши библиотеки используют обычный css, то лучше
470
+ использовать `compat` режим.
471
+
472
+ ## Shadow dom
473
+ [Shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM) - это спецификация, которая позволяет
474
+ создавать изолированные DOM-деревья, которые не будут влиять на DOM-дерево родительского элемента.
475
+
476
+ arui-scripts предоставляет возможность использовать shadow dom для модулей. Для этого вам нужно:
477
+
478
+ - На стороне модуля - использовать `arui-scripts` старше `15.9.2`.
479
+ - На стороне потребителя - указать параметр `useShadowDom` в `useModuleMounter`:
480
+
481
+ ```tsx
482
+ import {
483
+ createModuleLoader,
484
+ createModuleFetcher,
485
+ useModuleMounter,
486
+ MountableModule,
487
+ } from '@alfalab/scripts-modules';
488
+
489
+ const loader = createModuleLoader<MountableModule>({
490
+ hostAppId: 'bar-app',
491
+ moduleId: 'test',
492
+ getModuleResources: createModuleFetcher({
493
+ baseUrl: 'https://examle.com/foo-app',
494
+ }),
495
+ });
496
+
497
+ export const MyAwesomeComponent = () => {
498
+ const { loadingState, targetElementRef } = useModuleMounter({
499
+ loader,
500
+ useShadowDom: true, // !!!
501
+ });
502
+
503
+ return (
504
+ <div>
505
+ {loadingState === 'pending' && <div>pending...</div>}
506
+ {loadingState === 'rejected' && <div>Error</div>}
507
+ <div ref={targetElementRef} /> {/* сюда будет монтироваться модуль */}
508
+ </div>
509
+ );
510
+ }
511
+ ```
512
+
513
+ Этот режим работает как для _default_, так и для _compat_ модулей.
514
+ Внутри targetElementRef будет создаваться shadowRoot, и модуль и его стили будут монтироваться в него.
515
+
516
+ # Кеширование модулей
517
+
518
+ По умолчанию модули будут загружаться каждый раз при использовании. Если ваше приложение будет монтировать/размонтировать модуль несколько раз,
519
+ каждый раз загрузка модуля будет выполняться заново.
520
+ Это поведение можно изменить, с помощью параметра `resourcesCache` функции `createModuleLoader`.
521
+
522
+ ```tsx
523
+ const loader = createModuleLoader({
524
+ resourcesCache: 'single-item', // по умолчанию 'none'
525
+ // другие параметры
526
+ });
527
+ ```
528
+
529
+ Это включит кеширование модуля. В режиме `'single-item'` в кеше будут храниться ресурсы модуля для последнего значения `loaderParams`, если они переданы.
530
+ При повторном монтировании модуля с теми же `loaderParams`, ресурсы будут браться из кеша, а не загружаться заново.
531
+ При изменении `loaderParams` ресурсы будут загружаться заново.
532
+
533
+ Обратите внимание, что кеширование модулей может вызывать проблемы при обновлении приложения, поставляющего модуль.
534
+ Если сессии пользователей очень долгие, а обновления модуля происходят часто, то это может привести к тому, что пользователи будут продолжать видеть старую версию модуля.
535
+ Так же стоит помнить что кеширование может увеличить потребление памяти вашим приложением. Используйте его с осторожностью и только в случае если вы уверены, что оно действительно необходимо.
536
+ Как альтернативу стоит рассмотреть использование кеширования на уровне http протокола, это дает приемлемую скорость работы без рисков утечки памяти и использования "старой" версии ресурсов.
537
+
538
+ **Внимание!** Использование `resourcesCache: 'single-item'` не будет работать вместе с `useShadowDom` из-за особенностей работы со стилями.
539
+
540
+ # Другие типы модулей
541
+
542
+ Помимо создания монтируемых модулей, есть возможность создавать и другие типы модулей, более подходящие для некоторых вариантов использования.
543
+
544
+
545
+ ## Модули-фабрики
546
+ Модули-фабрики - это модули, которые поставляют фабрики, которые в свою очередь вызываются в рантайме со стейтом (клиентским или серверным, в зависимости от типа поставляемого модуля).
547
+
548
+ Такие модули должны экспортировать фабрику:
549
+
550
+ Для default модулей:
551
+
552
+ ```tsx
553
+ import type { FactoryModule } from '@alfalab/scripts-modules';
554
+
555
+ const factory: FactoryModule = function (runParams, serverState) {
556
+ // serverState - это состояние, которое подготовлено на сервере модуля
557
+ // runParams - это параметры, которые были переданы при запуске модуля клиентом
558
+ // в фабрике можно на основе стейта вернуть готовый модуль
559
+ return {
560
+ serverState,
561
+ doSomething: () => {
562
+ fetch(serverState.baseUrl + '/api/getData')
563
+ }
564
+ };
565
+ }
566
+
567
+ export default factory;
568
+ // или export { factory };
569
+ ```
570
+
571
+ для compat модулей:
572
+ ```ts
573
+ import type { FactoryModule } from '@alfalab/scripts-modules';
574
+
575
+ const factory: FactoryModule = function (runParams, serverState) {
576
+ // в фабрике можно на основе стейта вернуть готовый модуль
577
+ return {
578
+ serverState,
579
+ doSomething: () => {
580
+ fetch(serverState.baseUrl + '/api/getData')
581
+ }
582
+ };
583
+ }
584
+
585
+ window.ModuleCompat = factory;
586
+ ```
587
+
588
+ Серверный эндпоинт для таких модулей создается абсолютно так же, как и для монтируемых модулей.
589
+
590
+ ### Подключение модулей-фабрик в приложении потребителе
591
+
592
+ Для подключения модулей-фабрик можно использовать хук `useModuleFactory`:
593
+
594
+ ```tsx
595
+ import {
596
+ createModuleLoader,
597
+ createModuleFetcher,
598
+ FactoryModule,
599
+ useModuleFactory,
600
+ } from '@alfalab/scripts-modules';
601
+
602
+ const loader = createModuleLoader<FactoryModule>({
603
+ hostAppId: 'bar-app',
604
+ moduleId: 'test',
605
+ getModuleResources: createModuleFetcher({ // или createServerStateModuleFetcher для модулей с серверным состоянием
606
+ baseUrl: 'https://examle.com/foo-app',
607
+ }),
608
+ });
609
+
610
+ export const MyAwesomeComponent = () => {
611
+ const { loadingState, module } = useModuleFactory({ loader });
612
+
613
+ return (
614
+ <div>
615
+ { loadingState === 'pending' && <div>pending...</div> }
616
+ { loadingState === 'rejected' && <div>Error</div> }
617
+ <pre>{ JSON.stringify(module) }</pre> {/* модуль будет содержать то, что вернула фабрика */}
618
+ </div>
619
+ );
620
+ }
621
+ ```
622
+
623
+ Если вы хотите использовать модуль-фабрику вне реакт-компонента, вы можете использовать другой метод:
624
+
625
+ ```ts
626
+ import {
627
+ createModuleLoader,
628
+ createModuleFetcher,
629
+ FactoryModule,
630
+ executeModuleFactory,
631
+ } from '@alfalab/scripts-modules';
632
+
633
+ const loader = createModuleLoader<FactoryModule>(/*...*/);
634
+
635
+ (async () => {
636
+ const loaderResult = await loader();
637
+
638
+ const executionResult = executeModuleFactory(
639
+ result.module,
640
+ result.moduleResources.moduleState,
641
+ {}, // опциональные run-параметры модуля
642
+ );
643
+
644
+ console.log(executionResult); // Тут будет то, что возвращает модуль-фабрика
645
+ })();
646
+ ```
647
+
648
+ ## Абстрактные модули
649
+
650
+ Для совсем сложных кейсов, когда вам нужен полный контроль над всем тем, что делает код из модуля, вы можете использовать
651
+ абстрактные модули. Они могут иметь абсолютно любую структуру, экспортировать из себя любые методы и константы.
652
+
653
+ ```tsx
654
+ // src/modules/abstract-module/index.ts
655
+ export const doSomething = () => {
656
+ console.log('Hello from abstract module!');
657
+ };
658
+
659
+ export const publicConstant = 3.14;
660
+
661
+ window.AbstractModule = { // для compat модулей
662
+ doSomething,
663
+ publicConstant,
664
+ };
665
+ ```
666
+
667
+ Для подключения вы можете использовать хук `useModuleLoader`:
668
+
669
+ ```tsx
670
+ import {
671
+ createModuleLoader,
672
+ createModuleFetcher,
673
+ useModuleLoader,
674
+ } from '@alfalab/scripts-modules';
675
+
676
+ type CustomModule = {
677
+ doSomething: () => void;
678
+ publicConstant: number;
679
+ }
680
+
681
+ const loader = createModuleLoader<CustomModule>({
682
+ hostAppId: 'bar-app',
683
+ moduleId: 'test',
684
+ getModuleResources: createModuleFetcher({
685
+ baseUrl: 'https://examle.com/foo-app',
686
+ }),
687
+ });
688
+
689
+ export const MyAwesomeComponent = () => {
690
+ const { loadingState, module } = useModuleLoader({ loader });
691
+
692
+ return (
693
+ <div>
694
+ { loadingState === 'pending' && <div>pending...</div> }
695
+ { loadingState === 'rejected' && <div>Error</div> }
696
+ <pre>{ JSON.stringify(module) }</pre> {/* модуль будет содержать то, что экспортирует модуль, то есть doSomething и publicConstant */}
697
+ </div>
698
+ );
699
+ }
700
+ ```
701
+
702
+ # Тестирование модулей
703
+ Поскольку в общем случае модули представляют собой простой js код - для тестирования вы можете пользоваться любыми привычными вам инструментами.
704
+
705
+ Для тестирования модулей в cypress или playwright вы можете создать отдельный эндпоинт в вашем приложении, который будет
706
+ подключать модуль в ваше же приложение.
707
+
708
+
709
+ # Документация API
710
+
711
+ ## Конфигурация модулей
712
+ Типы, которые используются для конфигурирования модулей в `arui-scripts.config.ts`:
713
+
714
+ ### Modules
715
+ ```ts
716
+ type Modules = {
717
+ name?: string; // имя приложения, которое будет исползоваться как имя module federation контейнера. По-умолчанию будет использовано имя из package.json (оно будет преобразовано в snake-case)
718
+ exposes?: { // модули, которые приложение будет предоставлять
719
+ [moduleId: string]: string; // moduleId - id модуля, value - путь до точки входа модуля
720
+ };
721
+ shared?: (string | SharedObject)[] | SharedObject; // конфигурация shared параметра для ModuleFederationPlugin
722
+ };
723
+
724
+ type SharedObject = {
725
+ [index: string]: string | SharedConfig;
726
+ };
727
+
728
+ type SharedConfig = {
729
+ eager?: boolean; // включить модуль в сборку приложения
730
+ import?: string | false; // путь до модуля, который будет предоставлен в share scope
731
+ packageName?: string; // имя пакета, из которого будет взята версия модуля
732
+ requiredVersion?: string | false; // версия модуля, которая будет использована для проверки версии модуля в share scope
733
+ shareKey?: string; // ключ, по которому будет искаться модуль в share scope
734
+ shareScope?: string; // имя share scope
735
+ singleton?: boolean; // использовать только одну версию модуля в share scope
736
+ strictVersion?: boolean; // использовать только версию модуля, которая указана в requiredVersion
737
+ version?: string | false; // версия модуля, которая будет использована для проверки версии модуля в share scope
738
+ }
739
+ ```
740
+
741
+ ### CompatModules
742
+ ```ts
743
+ type CompatModules = {
744
+ shared?: { // библиотеки, которые будут доступны compat модулям при подключении в этом приложении
745
+ [libraryName: string]: string; // libraryName - имя библиотеки, которое вы указали в package.json, value - название глобальной переменной, в которой будет доступна библиотека
746
+ };
747
+ exposes?: { // модули, которые приложение будет предоставлять
748
+ [moduleId: string]: CompatModuleConfig;
749
+ };
750
+ };
751
+
752
+ type CompatModuleConfig = {
753
+ entry: string; // путь до точки входа модуля
754
+ externals?: Record<string, string>; // список библиотек, которые модуль будет пытаться получить из приложения, в которое он будет встроен. Аналогично CompatModules.shared
755
+ cssPrefix?: false | string; // опционально, префикс для css-классов модуля. По-умолчанию будет использовано имя модуля
756
+ };
757
+ ```
758
+
759
+ ## Конфигурация серверной части
760
+
761
+ ### createGetModulesMethod
762
+ ```ts
763
+ type ModulesConfig = {
764
+ [moduleId: string]: {
765
+ mountMode: 'compat' | 'default'; // режим монтирования модуля
766
+ version?: string; // версия модуля, по умолчанию 'unknown'
767
+ getModuleState: GetModuleStateMethod; // метод, который будет вызван для получения состояния модуля
768
+ };
769
+ };
770
+
771
+ type GetModuleStateMethod = (
772
+ getResourcesRequest: GetResourcesRequest,
773
+ ) => Promise<any>;
774
+
775
+ type GetResourcesRequest<GetResourcesParams = void> = {
776
+ moduleId: string; // id загружаемого модуля
777
+ hostAppId: string; // id приложения-хоста
778
+ params: GetResourcesParams; // параметры, которые передаются в функцию получения ресурсов модуля
779
+ };
780
+ ```