Types for jsApi
npm install @nsmp/js-apiПакет предназначен для разработчиков встроенных приложений и предоставляет инструменты для улучшения и оптимизации процесса разработки. Пакет предоставляет:
- Функцию initializeJsApi для подключения jsApi в разных режимах (development, test, production);
- Данная функция содержит проксирование, которое в зависимости от окружения создает объект jsApi.
- Каждое окружение содержит объект jsApi со своим интерфейсом, который преобразовывается в объект с общим интерфейсом, что позволяет при разработке ВП использовать единый интерфейс вне зависимости от окружения.
- На текущий момент существует 3 окружения:
- smp4 - ВП встраивается в страницу устаревшего GWT-интерфейса внутрь iframe,
- uiFrame - ВП встраивается в страницу нового react-интерфейса внутрь iframe,
- ui - ВП встраивается в страницу нового react-интерфейса как microfrontend.
- Функция принимает объект настроек, который содержит свойства:
- mock - для определения mock объекта jsApi для локальной разработки;
- getContext - функция возвращает контекст приложения, если оно выведено как microfrontend;
- Функцию getJsApi для получения созданного объекта jsApi, если он создан, иначе выбрасывает ошибку, что объект не создан;
- Функцию removeJsApi для удаления созданного объекта jsApi;
- Хук useInitializeJsApi для подключения jsApi в microfrontend приложении, использующем react. При размонтировании приложения хук вызывает функцию removeJsApi. Это необходимо, чтобы удалился singleton-объект jsApi для экономии памяти и смены контекста.
- Файлы декларации типов .d.ts для jsApi при работе с TypeScript;
- Mock-функции jsApi для локальной разработки, а также инструменты для их переопределения и уточнения;
- Инструменты для локальной разработки с проксированием запросов к приложению.
- Быстрый старт
- Инициализация и использование jsApi
- Типизация jsApi
- Переопределение методов jsApi
- Конфигурации
- Настройка проксирования запросов
1. Установить пакет: ``npm i @nsmp/js-api`jsApi
2. Инициализировать в проекте - Инициализация и использование jsApijsApi
3. В режиме разработки (при необходимости):
1. переопределить стандартные методы - Переопределение методов jsApi
2. настроить проксирование запросов - Настройка проксирования запросов
Инициализация jsApi зависит от того, в каком окружении будет использоваться ВП.
Пример для ВП с использованием контекста:
Необходимо в корневом компоненте, обычно это App, вызвать хук useInitializeJsApi и передать в него контекст приложения.microfrontend
Приложение как - это react-компонент, который принимает контекст через props компонента.
Импорт хука и функций для работы с jsApi для react приложений осуществляется по пути @nsmp/js-api/react.
`tsx
import {JsApiComponentProps, useInitializeJsApi, getJsApi} from '@nsmp/js-api/react';
const EmbeddedApp = () => {
const jsApi = getJsApi();
return (
const App = (props: JsApiComponentProps) => {
const {context} = props;
useInitializeJsApi({
getContext: () => context
});
return (
);
};
`
Пример использования с расширением методов jsApi через моки:
`tsx
import {deepMergeJsApi, getJsApi, IJsApi, JsApiComponentProps, jsApiMock, useInitializeJsApi} from '@nsmp/js-api/react';
// @nsmp/partial-js-api - используется в качестве примера, в реальности пакет не существует
import {IPartialJsApi, partialApiMock} from '@nsmp/partial-js-api';
const EmbeddedApp = () => {
const jsApi = getJsApi
return (
const App = (props?: JsApiComponentProps) => {
useInitializeJsApi
// В режиме разработки методы из переменной partialApiMock переопределят методы jsApi, которые есть в библиотеке
mock: process.env.NODE_ENV !== 'production' ? partialApiMock : {}
});
return (
);
};
`mock
Объект это объект с таким же интерфейсом, как и объект jsApi в режиме production, но у него своя реализация методов под нужды разработки.
Пример:
`typescript
import {initializeJsApi, getJsApi} from '@nsmp/js-api';
// В режиме development будут использоваться методы jsApi, которые определены в пакете @nsmp/js-api с помощью mock объекта
// Контекст берется автоматически из окружения, можно не передавать
initializeJsApi();
const jsApi = getJsApi();
jsApi.findContentCode();
`
Или
`typescript
import {initializeJsApi, IJsApi} from '@nsmp/js-api';
import {IMockApi, mockJsApi} from 'mocks/mockJsApi';
// В режиме development методы из переменной mockJsApi переопределят методы jsApi, которые есть в библиотеке
initializeJsApi
const jsApi = getJsApi
jsApi.findContentCode();
`
Пакет предоставляет типы для методов jsApi в TypeScript:JsApi
- - включает все методы jsApi. Требует указания всех методов пакета, заменяя их новымиPartialJsApi
- - также включает все методы, но позволяет переопределять только необходимые, оставляя остальные без изменений
Если нужно создать моки с частичным переопределением функций, а затем передать их в initializeJsApi, следует использовать тип PartialJsApi при создании моков.
Пример:
`typescript
import {PartialJsApi} from '@nsmp/js-api';
const mock: PartialJsApi = {
extractSubjectUuid () {
return 'subjectUuid$123';
},
findContentCode () {
return 'contentCode';
},
}
initializeJsApi(mock)
`
В пакете есть возможность переопределить стандартные методы. Для этого необходимо создать переменную в проекте, которая будет хранить новые значения методов jsApi, например:
`typescript
import {PartialJsApi} from '@nsmp/js-api';
// При работе с TypeScript указан тип PartialJsApi
const mockJsApi: PartialJsApi = {
extractSubjectUuid () {
return 'subjectUuid$123';
},
findContentCode () {
return 'contentCode';
},
getCurrentUser () {
return {
uuid: 'user$123'
};
},
urls: {
objectCard: (uuid: string) => /${uuid}`
}
};
При работе с TypeScript переменной с моковыми методами jsApi можно указать тип PartialJsApi из данного пакета - Типизация jsApi
Для корректной работы react приложений необходимо в файле tsconfig.json добавить настройку:
`json`
{
"compilerOptions": {
"moduleResolution": "bundler"
}
}
Это необходимо, чтобы путь @nsmp/js-api/react воспринимался компилятором
moduleResolution: "bundler" нельзя использовать с ts-jest — он не поддерживает этот режим. Для корректной работы jest необходимо создать новый файл конфигурации, например, tsconfig.test.json. В файле tsconfig.test.json добавить настройку:
`json`
{
"compilerOptions": {
"moduleResolution": "node"
}
}
Хук useInitializeJsApi использует подключение react. Т.к. react не устанавливается в этом пакете, то он использует пакет из внешнего приложения.jest
При работе с может возникать ошибка, что в этом пакете нет react.
Для исправления проблемы нужно добавить настройку в файл jest.confing.js:
`javascript`
module.exports = {
moduleNameMapper: {
'^react$': require.resolve('react')
}
}
Для подключения нового файла конфигурации, например, tsconfig.test.json нужно добавить настройку в файл jest.confing.js:
`javascript`
module.exports = {
transform: {
'^.+\\.[t|j]sx?$': ['ts-jest', {
tsconfig: 'tsconfig.jest.json'
}]
}
}
Пакет имеет возможность проксирования запросов в режиме локальной разработки приложения. Чтобы проксирование запросов работало правильно, необходимо создать файл dev.env и определить переменные окружения:ACCESS_KEY
- - ключ доступа для REST запросовAPP_URL
- - URL стендаAPP_CODE
- - код ВПCONTENT_CODE
- - код контента, на котором выведено ВПREST_PATH
- - путь REST запроса (rest или earest)SUBJECT_UUID
- - идентификатор объекта, на котором выведено ВПUSER_LOGIN
- - логин пользователяUSER_UUID
- - идентификатор пользователя
Пример:
`dotenv`
ACCESS_KEY=your-access-key
APP_URL=https://your-domain.ru/
APP_CODE=app_code
CONTENT_CODE=content_code
REST_PATH=earest
SUBJECT_UUID=subject$123
USER_LOGIN=your_login
USER_UUID=user$123
Также необходимо изменить строку запуска dev режима приложения в файле package.json, например:
- Было - "dev": "cross-env NODE_ENV=development webpack serve --mode=development --config ./webpack/config.js""dev": "cross-env NODE_ENV=development start-webpack-server --mode=development --config ./webpack/config.js --env ./dev.env"
- Стало -
config и env являются опциональными аргументами командной строки. Если они не указаны по стандарту будут браться пути:config
- - ./webpack/config.jsenv
- - ./dev.env
Команда start-webpack-server запускает webpack server с добавленным в него проксированием запросов и всеми переменными окружения из файла dev.env`