Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions .changeset/module-contracts.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
'arui-scripts': minor
'@alfalab/scripts-modules': minor
---

Добавлена генерация npm пакета с типами микрофронтов.
Хост-приложение может подключить этот пакет, чтобы typescript проверял имена модулей и параметры запуска.
8 changes: 8 additions & 0 deletions packages/arui-scripts-modules/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -597,3 +597,11 @@ Boundary автоматически не перехватывает. Для их
Очистка React root откладывается до микрозадачи, чтобы хост мог вызывать unmount во
время собственного commit. Повторный запуск в том же контейнере до этой очистки
сохраняет root, но создаёт новое дерево приложения с новым состоянием.

## Типы контрактов модулей

Включите `modules.types` в конфиге микрофронта, чтобы `arui-scripts` создал пакет с картой `ModuleContracts`.
Используйте ее с `createTypedModuleLoader<ModuleContracts>()`: идентификатор модуля определяет тип его экспорта,
а хуки проверяют переданные параметры. `ModuleRunParams<T>` и `ModuleServerState<T>` позволяют получить отдельные типы из контракта модуля или фабрики.

Пример настройки, публикации и подключения: [генерация пакета контрактов](../arui-scripts/docs/modules.md#генерация-пакета-контрактов).
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
import React, { useEffect, useRef } from 'react';

import { useModuleMountTarget } from './hooks/use-module-mount-target';
import { type ModuleExports } from './module-contract';
import { reportModuleError } from './module-lifecycle';
import {
createModuleSession,
Expand All @@ -19,7 +20,7 @@ type CreateLazyMounterParams<
RunParams,
ServerState extends BaseModuleState,
> = ModuleMounterOptions & {
loader: Loader<LoaderParams, MountableModule<RunParams, ServerState>>;
loader: Loader<LoaderParams, ModuleExports<MountableModule<RunParams, ServerState>>>;
/**
* Параметры, которые будут переданы в загрузчик (и будут переданы на сервер модуля)
*/
Expand Down Expand Up @@ -58,7 +59,7 @@ export function createLazyMounter<
}

let loadStage: ModuleMounterErrorStage = 'resolve-export';
let result: LoaderResult<MountableModule<RunParams, ServerState>>;
let result: LoaderResult<ModuleExports<MountableModule<RunParams, ServerState>>>;

try {
result = await loader({
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
import { createModuleLoader, type CreateModuleLoaderParams } from './create-module-loader';
import { type BaseModuleState } from './types';

// typeScript проверяет moduleId по контракту и подставляет тип модуля
export function createTypedModuleLoader<Contracts>() {
return function createLoader<
Id extends Extract<keyof Contracts, string>,
GetResourcesParams = undefined,
ModuleState extends BaseModuleState = BaseModuleState,
>(
params: Omit<
CreateModuleLoaderParams<Contracts[Id], GetResourcesParams, ModuleState>,
'moduleId'
> & { moduleId: Id },
) {
return createModuleLoader<Contracts[Id], GetResourcesParams, ModuleState>(params);
};
}
Original file line number Diff line number Diff line change
@@ -1,13 +1,20 @@
import { unwrapDefaultExport } from './utils/unwrap-default-export';
import { type ModuleExports } from './module-contract';
import { type FactoryModule } from './module-types';
import { type BaseModuleState } from './types';

export type FactoryModuleExports<
Result,
RunParams,
ServerState extends BaseModuleState,
> = ModuleExports<FactoryModule<Result, RunParams, ServerState>>;

export async function executeModuleFactory<
ModuleExportType,
RunParams = undefined,
ServerState extends BaseModuleState = BaseModuleState,
>(
module: FactoryModule<ModuleExportType, RunParams, ServerState>,
module: FactoryModuleExports<ModuleExportType, RunParams, ServerState>,
serverState: ServerState,
runParams?: RunParams,
): Promise<ModuleExportType> {
Expand Down
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
import { useEffect, useRef, useState } from 'react';

import { executeModuleFactory } from '../execute-module-factory';
import { type FactoryModule } from '../module-types';
import { executeModuleFactory, type FactoryModuleExports } from '../execute-module-factory';
import { type BaseModuleState, type Loader } from '../types';

import { type LoadingState } from './types';
Expand All @@ -17,7 +16,7 @@ export type UseModuleFactoryParams<
/**
* Загрузчик модуля
*/
loader: Loader<LoaderParams, FactoryModule<ModuleExportType, RunParams, ServerState>>;
loader: Loader<LoaderParams, FactoryModuleExports<ModuleExportType, RunParams, ServerState>>;
/**
* Параметры, которые будут переданы в загрузчик (и будут переданы на сервер модуля)
*/
Expand All @@ -40,7 +39,7 @@ export type UseModuleFactoryResult<ModuleExportType> = {
/**
* Экспорт модуля
*/
module: ModuleExportType | undefined;
module: Awaited<ModuleExportType> | undefined;
};

export function useModuleFactory<
Expand All @@ -62,7 +61,7 @@ export function useModuleFactory<
RunParams
>): UseModuleFactoryResult<ModuleExportType> {
const [loadingState, setLoadingState] = useState<LoadingState>('unknown');
const [module, setModule] = useState<ModuleExportType | undefined>();
const [module, setModule] = useState<Awaited<ModuleExportType> | undefined>();
// Мы не хотим чтобы изменение этих параметров тригерило ререндер и перемонтирование модуля,
// но не хотим ломать правила хуков
const loaderParamsRef = useRef(loaderParams);
Expand Down
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
import { useEffect, useRef, useState } from 'react';

import { type ModuleExports } from '../module-contract';
import { createModuleSession } from '../module-session';
import { type ModuleMounterOptions, type MountableModule } from '../module-types';
import { type BaseModuleState, type Loader } from '../types';
Expand All @@ -15,7 +16,7 @@ export type UseModuleLoaderParams<
/**
* Загрузчик модуля
*/
loader: Loader<LoaderParams, MountableModule<RunParams, ServerState>>;
loader: Loader<LoaderParams, ModuleExports<MountableModule<RunParams, ServerState>>>;
/**
* Параметры, которые будут переданы в загрузчик (и будут переданы на сервер модуля)
*/
Expand Down
2 changes: 2 additions & 0 deletions packages/arui-scripts-modules/src/module-loader/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,11 @@ import 'abortcontroller-polyfill/dist/abortcontroller-polyfill-only';

export * from './types';
export * from './module-types';
export * from './module-contract';
export * from './hooks/types';

export { createModuleLoader } from './create-module-loader';
export { createTypedModuleLoader } from './create-typed-module-loader';
export { createModuleFetcher } from './create-module-fetcher';
export { createServerStateModuleFetcher } from './create-server-state-module-fetcher';
export { createEmbeddedModuleFetcher } from './create-embedded-module-fetcher';
Expand Down
39 changes: 39 additions & 0 deletions packages/arui-scripts-modules/src/module-loader/module-contract.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
// модуль может быть экспортирован напрямую или через default
export type ModuleExports<Module> =
| (Module & { default?: Module | null | undefined })
| { default: Module };

type DefaultOrModule<Module, Default> = Default extends null | undefined ? Module : Default;

// берем default, а при null или undefined используем сам модуль
type UnwrapModule<Module> = Module extends { default?: unknown }
? 'default' extends keyof Module
? DefaultOrModule<Module, Module['default']>
: Module
: Module;

// распознает функцию без ограничений на типы ее аргументов
type Callable = (...args: never[]) => unknown;

// фабрика может быть самой функцией, полем factory или старым полем mount
type FactoryFunction<Module> = Module extends Callable
? Module
: Module extends { factory: infer Factory extends Callable }
? Factory
: Module extends { mount: infer Factory extends Callable }
? Factory
: never;

// у mount пропускаем первый аргумент (DOM-элемент), а у фабрики берем аргументы как есть
type ModuleArguments<Module> = Module extends {
mount: infer Mount extends Callable;
unmount: Callable;
}
? [Parameters<Mount>[1], Parameters<Mount>[2]]
: Parameters<FactoryFunction<Module>>;

// тип параметров запуска модуля или фабрики
export type ModuleRunParams<Module> = ModuleArguments<UnwrapModule<Module>>[0];

// тип серверного состояния, которое ожидает модуль или фабрика
export type ModuleServerState<Module> = ModuleArguments<UnwrapModule<Module>>[1];
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
import { MODULE_SSR_MODULE_ATTRIBUTE } from './utils/get-embedded-module-resources';
import { unwrapDefaultExport } from './utils/unwrap-default-export';
import { type ModuleExports } from './module-contract';
import { createModuleLifecycle, reportModuleError } from './module-lifecycle';
import {
type ModuleMounterErrorStage,
Expand All @@ -12,15 +13,15 @@ type SessionParams<RunParams, ServerState extends BaseModuleState> = {
load: (
signal: AbortSignal,
onLoadError: (stage: ModuleMounterErrorStage) => void,
) => Promise<LoaderResult<MountableModule<RunParams, ServerState>>>;
) => Promise<LoaderResult<ModuleExports<MountableModule<RunParams, ServerState>>>>;
targetNode: HTMLElement;
getRunParams: () => RunParams;
getOptions: () => ModuleMounterOptions;
hydrate?: boolean;
};

export function resolveMountableModule<RunParams, ServerState extends BaseModuleState>(
exportedModule: MountableModule<RunParams, ServerState>,
exportedModule: ModuleExports<MountableModule<RunParams, ServerState>>,
) {
const module = exportedModule && unwrapDefaultExport(exportedModule);

Expand Down Expand Up @@ -52,7 +53,9 @@ export function createModuleSession<RunParams, ServerState extends BaseModuleSta
let stage: ModuleMounterErrorStage = 'resolve-export';

async function run() {
let result: LoaderResult<MountableModule<RunParams, ServerState>> | undefined;
let result:
| LoaderResult<ModuleExports<MountableModule<RunParams, ServerState>>>
| undefined;

try {
result = await load(abortController.signal, (errorStage) => {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -135,7 +135,7 @@ export type FactoryModule<
ServerState extends BaseModuleState = BaseModuleState,
> =
| FactoryModuleFunction<ReturnType, RunParams, ServerState>
| { factory: FactoryModuleFunction<ReturnType, RunParams, ServerState>; mount: never }
| { mount: FactoryModuleFunction<ReturnType, RunParams, ServerState>; factory: never };
| { factory: FactoryModuleFunction<ReturnType, RunParams, ServerState>; mount?: never }
| { mount: FactoryModuleFunction<ReturnType, RunParams, ServerState>; factory?: never };

export type WindowWithFactoryModule = WindowWithModule<FactoryModule>;
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
type ModuleWithDefaultField<T> = {
default: T;
};
import { type ModuleExports } from '../module-contract';

export function unwrapDefaultExport<ModuleExportType>(module: ModuleExportType): ModuleExportType {
return (module as ModuleWithDefaultField<ModuleExportType>).default ?? module;
export function unwrapDefaultExport<ModuleExportType>(
module: ModuleExports<ModuleExportType>,
): ModuleExportType {
return module.default ?? (module as ModuleExportType);
}
4 changes: 4 additions & 0 deletions packages/arui-scripts-modules/src/react/index.ts
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
export { createReactModule } from './create-react-module';
export { useModuleReady } from './module-runtime';
export { type ReactModuleProps, type CreateReactModuleOptions } from './types';
// типы из сигнатуры createReactModule: без них TypeScript не может назвать выведенный тип
// модуля через публичный подпуть, и генерация контрактов падает с TS2883
export { type MountableModule } from '../module-loader/module-types';
export { type BaseModuleState } from '../module-loader/types';
3 changes: 3 additions & 0 deletions packages/arui-scripts/docs/commands.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,9 @@ arui-scripts start:prod

Если заданы [buildSizeBudgets](settings.md#buildsizebudgets), после клиентской сборки проверяются лимиты начального JS и CSS. Превышение останавливает сборку с ненулевым кодом.

Если задан `modules.types`, команда также готовит npm пакет с типами в `<buildPath>/module-contracts`.
Подробнее в разделе [генерация пакета контрактов](modules.md#генерация-пакета-контрактов).

**Как запустить?**

```bash
Expand Down
67 changes: 65 additions & 2 deletions packages/arui-scripts/docs/modules.md
Original file line number Diff line number Diff line change
Expand Up @@ -174,8 +174,8 @@ export const mount: ModuleMountFunction<ModuleRunParams> = (targetNode, runParam
```tsx
import { createModuleLoader, MountableModule, useModuleMounter } from '@alfalab/scripts-modules';

// У нас возможности передать типы из приложения-модуля в приложение-хост
// При желании вы можете вынести эти типы в общую библиотеку и использовать оттуда
// Без генерации контрактов типы нужно описать вручную
// или вынести в общую библиотеку. Автоматическая генерация описана ниже.
type ModuleRunParams = {
theme: string;
width: number;
Expand All @@ -200,6 +200,69 @@ export const MyAwesomeComponent = () => {
}
```

## Генерация пакета контрактов

Пакет контрактов позволяет хосту использовать типы микрофронта без ручного копирования

### В микрофронте

Укажите в конфиге, какие модули экспортировать и задайте имя npm пакета с их типами

```ts
export default {
modules: {
shared: {},
exposes: {
SomeWidget: './src/modules/some-widget/index'
},
types: {
packageName: '@namespace/some-widget-contracts'
},
},
};
```

`arui-scripts build` создаст пакет в `<buildPath>/module-contracts`.
При стандартном `buildPath` опубликуйте его отдельной командой `npm publish ./.build/module-contracts`.

По умолчанию версия берется из `package.json` микрофронта.
Переопределить ее можно через `modules.types.version`. Сборка проверяет формат semver.

### В хосте

Установите пакет как `devDependency` и добавьте недостающие зависимости из его `peerDependencies`.
Передайте `ModuleContracts` в `createTypedModuleLoader`.

```tsx
import type { ModuleContracts } from '@namespace/some-widget-contracts';
import { createModuleFetcher, createTypedModuleLoader, useModuleMounter } from '@alfalab/scripts-modules';

const createLoader = createTypedModuleLoader<ModuleContracts>();

const loader = createLoader({
moduleId: 'SomeWidget',
hostAppId: 'some-host',
getModuleResources: createModuleFetcher({ baseUrl: '/some-widget' }),
});

export const SomeWidget = () => {
const { targetElementRef } = useModuleMounter({
loader,
runParams: { clientId: '123', width: 300 },
});

return <div ref={targetElementRef} />;
};
```

TypeScript проверит `moduleId` и переданные `runParams`.
Например, если `width` у микрофронта имеет тип `number`, строка `'300'` вызовет ошибку.
Весь объект `runParams` можно опустить. Используйте версию контракта, соответствующую развернутому микрофронту.

Для генерации нужен TypeScript 5.x или 6.x.
Compat-модули и project references не поддерживаются.
Чтобы отключить генерацию, задайте `modules.types: false`.

:warning: **Внимание!** Модуль не будет обновляться при изменении runParams. Это осознанное решение, вы не должны относится к
параметрам тут с той же легкостью, что и к prop-ам react-компонентов. Очень легко провести параллели между эти двумя
концепциями, но использование runParams специально сделано менее удобным - чем меньше вы их используете, тем реже вы будете
Expand Down
2 changes: 2 additions & 0 deletions packages/arui-scripts/docs/settings.md
Original file line number Diff line number Diff line change
Expand Up @@ -385,6 +385,8 @@ export default settings;
#### modules
Позволяет настроить работу с модулями. По умолчанию `{}`. Подробнее в разделе [модули](modules.md).

`modules.types: { packageName: '@namespace/module-contracts', version?: string }` включает подготовку npm пакета деклараций из `modules.exposes` при production-сборке. `version` по умолчанию берется из `package.json` приложения. По умолчанию генерация выключена; `modules.types: false` явно отключает настройку из preset. Подробнее в разделе [генерация пакета контрактов](modules md#генерация-пакета-контрактов).

#### compatModules
Позволяет настроить работу с `compat` модулями. По умолчанию `{}`. Подробнее в разделе [модули](modules.md).

Expand Down
1 change: 1 addition & 0 deletions packages/arui-scripts/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -136,6 +136,7 @@
"webpack-node-externals": "3.0.0"
},
"devDependencies": {
"@alfalab/scripts-modules": "workspace:*",
"@rsdoctor/types": "1.6.4",
"@types/assets-webpack-plugin": "6.1.2",
"@types/case-sensitive-paths-webpack-plugin": "2.1.6",
Expand Down
3 changes: 3 additions & 0 deletions packages/arui-scripts/src/commands/build/client.ts
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ import { rspackClientConfig } from '../../configs/rspack.client.prod';
import { BuildSizeBudgetError, checkBuildSizeBudgets } from '../util/build-size-budgets';
import { printAssetsSizes } from '../util/client-assets-sizes';
import { loadBrowserslist } from '../util/load-browserslist';
import { buildModuleContracts } from '../util/module-contracts/build-module-contracts';
import { printBuildError } from '../util/print-build-error';
import { enableRsdoctor, writeRsdoctorSnapshot } from '../util/rsdoctor-snapshot';

Expand Down Expand Up @@ -72,6 +73,8 @@ async function main() {
if (snapshot) {
await writeRsdoctorSnapshot(snapshot);
}

buildModuleContracts(configs);
} catch (err) {
if (err instanceof BuildSizeBudgetError) {
process.exit(1);
Expand Down
Loading
Loading