@vetsnakara/uikit-react

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)

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

1. npm version patch
2. npm publish

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

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

Использование UIKit React в проекте ПРР

• uikit-react - ветка в репозитории ПРР, настроенная для использования UIKit React
• установка
• скрипты
• разработка через Storybook

Разработка компонентов и инфоблоков через Storybook

• конфигурация
• глобальные стили
• MSW
• разработки инфоблоков через Storybook