@vetsnakara/uikit-react NPM

UIKit React

GitHub: https://github.com/vetsnakara/uikit-react

NPM: https://www.npmjs.com/package/@vetsnakara/uikit-react

Что это и зачем нужно

Репозиторий содержит библиотекy компонентов UIKit React, разработанную на основе дизайн-системы, используемой на ПРР (link).

Текущей реализацией дизайн-системы является базовый UIKit, который предоставляет для разработки инфоблоков разметку, систему классов для стилизации и набор скриптов для инициализации компонентов. Переиспользование компонентов реализовано только на уровне разметки, стилей и базовой логики, но не для всех составляющих компонента вместе.

Использование React позволяет инкапсулировать все составляющие компонента (разметку, стили и логику), тем самым повысив степень переиспользования компонентов. Данный подход призван увеличить скорость разработки, снизив количество кастомных решений при реализации стандартного функционала.

Приципы использования UIKit React

Код библиотеки UIKit React оформляется в виде отдельного репозитория. Весь код базового UIKit переносится в репозиторий UIKit React (исходный код, конфиги и зависимости для сборки статики), и все последующие доработки базового UIKit осуществляются в рамках репозиотрия UIKit React. Это позволит синхронизировать код базового UIKit с кодом React-компонентов. Библиотека UIKit React вместе с базовым UIKit оформляется в виде NPM-пакета, после чего библиотека подключается в проект отдельной зависимостью. Появляется возможность использовать разные версии библиотеки в разных ветках проекта и обновлять версию, когда это необходимо.
Стандарные механизмы разработки, сборки и деплоя инфоблоков остаются прежними. У разработчика появляется дополнительная возможность создания интерфейсов на React при помощи библиотеки компонентов UIKit React. При этом нет необходимости использовать React для решения любых задач на ПРР. Реализация существующих инфоблоков остается в рамках базового подхода. При создании новых инфоблоков, требующих реализации сложных интерфейсов, предлагается использовать React вместе с UIKit React.
UIKit React использует систему стилей базового UIKit. Генерируемая разметка полностью соответствует разметке компонентов в базовом UIKit. Разработчик не имеет дело с разметкой напрямую и не пишет классы от руки. Настройка внешнего вида и поведения компонентов призводится в клиентском коде с помощью пропсов.
UIKit React старается, где это возможно, переиспользовать логику, реализованную в рамках базового UIKit. Например, для компонентов, которые базируются на jQuery-плагинах, делаются соответствующие обертки в рамках React-компонентов. В первую очередь это касается компонентов Select и DateInput. Такой подход позволяет сохранить привычные настройки компонентов и сделать переход на UIKit React в рамках ПРР максимально удобным.
UIKit React не требует использования библиотеки для управленя состоянием. При необходимости с UIKit React может быть использована любая библиотека управленя состоянием (напр. Redux, MobX и др.). Но в базовом варианте для управления состоянием достаточно стандартных средств React (useState, useReducer, useContext).
Для унификации логики работы с формами и работы с серверным состоянием предлагается использовать хуки из библиотек react-hook-form (link) и react-query (link). Самостоятельная реализация функциональности данных библиотек является сложной и трудозатратной задачей.
Для задач фильтрации, пагинации и сортировки библиотека UIKit React предлагает кастомный хук useFilter, который инкапсулирует логику работы со списочными страницами.

Инструменты

Webpack - сборка библиотеки React-компонентов
Gulp / Grunt - сборка статики базового UIKit
ESLint - линтинг кода
Stylelint - линтинг стилей
Prettier - форматирование кода
Typescript - генерация TS-типов на основе JSDoc-описаний компонентов (для автокомплита при использовании библиотеки)
Storybook - создание витрины компонентов
Husky - работа с git-hooks

CI и pre-commit хуки

В pre-commit хуках производится линтинг и форматирование кода, а также пересборка библиотеки, если изменились соответствющие файлы исходного кода.
В .github/workflows находится конфигурация Github Actions для сборки и публикации Storybook на Github Pages

Основные зависимости (peerDeps)

react / react-dom - React
react-hook-form - хуки для работы с формами
@tanstack/react-query - хуки для работы с серверным состоянием
axios - выполнение сетевых запросов
yup - валидация пользовательского ввода (нужен как зависимость или удалить?)

Особенности сборки

🛑 peerDependencies

Скрипты

build:all - полная сборка пакета библиотеки перед публикацией
- build:assets - сборка статики базового UIKit в каталог assets
- build:dev - сборка бандла библиотеки в DEV-режиме в каталог lib
- build:prod - сборка бандла библиотеки в PROD-режиме в каталог сборки lib
- gen-types - генерация типов для автокоплита в месте использованя библиотеки (каталог размещения типов lib/types)
- move-bundle - перемещение бандла uikit-react.min.js из lib в assets/redesign-theme/scripts
storybook - запуск Storybook в режиме разработки (с проверкой существования собранной статики базового UIKit)

Публикация новой версии библиотеки

npm version patch
npm publish

Локальная разработка библиотеки

В каталоге репозитория uikit-react выполнить команду npm link для создания глобальной ссылки на пакет
В каталоге репозитория bft-portal-platform-site-prr выполнить команду npm link @vetsnakara/uikit-react для работы с пакетом через глобальную ссылку
При завршении разработки:
1. Удалить глобальную ссылку на пакет командой npm r -g @vetsnakara/uikit-react
2. В каталоге репозитория bft-portal-platform-site-prr отвязать пакет от глобальной ссылки командой npm unlink @vetsnakara/uikit-react