Продвинутый старт (TypeScript)

В данном разделе представлена пошаговая инструкция по развертыванию проекта кастомизации системы с использованием
TypeScript, JSX и инструмента сборки Vite. В отличие от быстрого старта, данный вариант ориентирован на полноценную разработку: он обеспечивает строгую типизацию и предоставляет все преимущества модульной сборки.

В качестве примера будет реализован проект, добавляющий декларацию точки расширения Universe.App.UERightHeaderItem в продуктовое приложение.

Шаг 1. Настройка окружения

1. Установить необходимое окружение:

   • Docker — для запуска приложения продукта в docker-контейнере
   • Node.js + NPM — для сборки внешнего модуля кастомизации

2. Выполнить вход в Docker-репозиторий:

   docker login repository.universe-data.ru
   Копировать

   Совет

   Для получения имени пользователя и пароля для доступа к Docker-репозиторию необходимо обратиться в службу поддержки

3. Выполнить вход в NPM-репозиторий:

   npm login --scope=universe-dg --registry=https:https://repository.universe-data.ru/repository/npm-lib/
   Копировать

   Совет

   Для получения имени пользователя и пароля для доступа к NPM-репозиторию необходимо обратиться в службу поддержки

Шаг 2. Создание проекта

Проект будет содержать следующую структуру файлов:

<project-root>
├─ src
│  ├─ CustomComponent.tsx
│  └─ index.ts
├─ customer.json
├─ package.json
├─ tsconfig.json
└─ vite.config.js
Копировать

1. Создать <project-root>/package.json выполнив команду:

   npm init -y
   Копировать

2. Установить зависимости:

   npm i -DE @universe-dg/sdk@2.15.0 \
             vite \
             vite-plugin-checker \
             @vitejs/plugin-react
   Копировать

   Важно

   @universe-dg/sdk@2.15.0 - пакет с декларациями типов для SDK продукта. Должен подключаться пакет той же версии, что и дистрибутив (docker-образ) приложения пользовательского интерфейса.

3. Создать файл <project-root>/src/CustomComponent.tsx:

   import {Universe} from '@universe-dg/sdk';
   
   const {React, MobxReact} = Universe.Vendor;
   const {Locale, Uikit} = Universe.Platform;
   
   Locale.i18n.addResourceBundle(Locale.Locales.Ru, {customComponent: {text: 'Нажми меня!'}});
   Locale.i18n.addResourceBundle(Locale.Locales.En, {customComponent: {text: 'Click me!'}});
   
   @MobxReact.observer
   export class CustomComponent extends React.Component {
       override render() {
           return (
               <Uikit.Button intent={Uikit.INTENT.DANGER}>
                   {Locale.i18n.t('customComponent>text')}
               </Uikit.Button>
           );
       }
   }
   Копировать

4. Создать основную точку входа, файл <project-root>/src/index.ts:

   import {Universe} from '@universe-dg/sdk';
   import {CustomComponent} from './CustomComponent';
   
   export default {
       userExits: [
           {
               type: 'RightHeaderItem',
               moduleId: 'uniqueId',
               active:true,
               system: false,
               resolver: () => true,
               meta: {
                   order: 1,
               },
               component: CustomComponent,
           }
       ],
   } satisfies Universe.Platform.UserExit.ExternalModuleDefault;
   Копировать

5. Создать конфигурационный файл <project-root>/customer.json:

   {
       "APP_TYPE": [],
       "serverUrl": "/universe-backend/api/",
       "EXTERNAL_MODULES": [
           "./CUX/index.es.js"
       ]
   }
   Копировать

   В свойстве EXTERNAL_MODULE указываются пути к внешним модулям, относительно корневой директории приложения в docker-контейнере: /usr/share/nginx/html/.
6. Создать файл <project-root>/tsconfig.json:

   {
       "extends": "@universe-dg/sdk/tsconfig.recommended.json",
       "files": ["src/index.ts"]
   }
   Копировать

   Где @universe-dg/sdk/tsconfig.recommended.json - typescript-конфигурация, рекомендованная для корректной компиляции
7. Создать конфигурационный файл сборки <project-root>/vite.config.js:

   import {defineConfig} from 'vite';
   import react from '@vitejs/plugin-react';
   import checker from 'vite-plugin-checker';
   
   export default defineConfig({
       plugins: [
           react({jsxRuntime: 'classic'}),
           checker({typescript: true}),
       ],
       build: {
           lib: {
               entry: 'src/index.ts',
               formats: ['es'],
               fileName: 'index'
           }
       }
   });
   Копировать

Шаг 3. Сборка и запуск

1. Собрать внешний модуль c помощью Vite:

   npx vite build
   Копировать

   Внешний модуль будет собран в файл <project-root>/dist/index.es.js.

2. Запустить docker-контейнер приложения:

   docker run repository.universe-data.ru/dis/unidata-dg/frontend:v2.15.0 \
       -p '80:80' \
       -v ./customer.json:/usr/share/nginx/html/customer.json \
       -v ./dist/index.es.js:/usr/share/nginx/html/CUX/index.es.js\
       -e BACKEND_ADDRESS=$BACKEND_ADDRESS 
   Копировать

   Где $BACKEND_ADDRESS - Адрес запущенного бэкенда системы (например: http://localhost:8080)

   Внутри docker-контейнера:

   • /usr/share/nginx/html/customer.json - Путь к файлу конфигурации приложения
   • /usr/share/nginx/html/CUX/ - Рекомендуемая директория для расположения внешних модулей

3. Приложение будет доступно по адресу: http://localhost. После запуска приложения, добавленную точку расширения можно увидеть в правом углу шапки.