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
для работы с пакетом через глобальную ссылку - При завршении разработки:
- Удалить глобальную ссылку на пакет командой
npm r -g @vetsnakara/uikit-react
- В каталоге репозитория
bft-portal-platform-site-prr
отвязать пакет от глобальной ссылки командойnpm unlink @vetsnakara/uikit-react
- Удалить глобальную ссылку на пакет командой
Использование UIKit React в проекте ПРР
-
uikit-react
- ветка в репозитории ПРР, настроенная для использования UIKit React - установка
- скрипты
- разработка через Storybook
Разработка компонентов и инфоблоков через Storybook
- конфигурация
- глобальные стили
- MSW
- разработки инфоблоков через Storybook