Совместимость версий

Библиотека Radix UI развивается по принципам строгой модульности и предсказуемости изменений. Пакеты библиотеки распространяются через npm и используют стандарт Semantic Versioning (SemVer), который определяет структуру номера версии и правила совместимости между релизами.

Каждый пакет Radix UI имеет собственную версию и может обновляться независимо. Это связано с архитектурой библиотеки: компоненты распространяются как отдельные npm-пакеты, например:

  • @radix-ui/react-dialog
  • @radix-ui/react-dropdown-menu
  • @radix-ui/react-tabs
  • @radix-ui/react-tooltip

Независимое версионирование позволяет обновлять только используемые компоненты, не затрагивая остальные зависимости проекта.

Семантическое версионирование (SemVer)

Radix UI придерживается стандарта SemVer, где версия имеет формат:

MAJOR.MINOR.PATCH

MAJOR

Увеличение MAJOR-версии означает наличие изменений, нарушающих обратную совместимость.

Примеры таких изменений:

  • изменение API компонента
  • удаление или переименование props
  • изменение структуры DOM компонентов
  • изменение логики работы accessibility-механизмов
  • изменение экспортируемых типов TypeScript

Пример:

@radix-ui/react-dialog 1.x → 2.0

При переходе на новую major-версию требуется проверка кода и возможная адаптация компонентов.

MINOR

Увеличение MINOR-версии означает добавление новых возможностей без нарушения обратной совместимости.

Типичные изменения:

  • добавление новых props
  • добавление новых компонентов
  • расширение типов TypeScript
  • улучшения accessibility
  • новые варианты поведения

Пример:

1.2.0 → 1.3.0

Код, написанный для предыдущей версии, продолжает работать без изменений.

PATCH

Версия PATCH увеличивается при исправлении ошибок без изменения API.

Примеры:

  • исправление багов
  • улучшение производительности
  • исправление поведения в edge-case сценариях
  • исправления типов TypeScript

Пример:

1.3.2 → 1.3.3

Такие обновления считаются полностью безопасными.

Независимое версионирование пакетов

Radix UI использует independent versioning, то есть разные компоненты могут иметь разные версии.

Пример зависимостей:

{
  "dependencies": {
    "@radix-ui/react-dialog": "^1.0.5",
    "@radix-ui/react-tabs": "^1.0.3",
    "@radix-ui/react-tooltip": "^1.1.0"
  }
}

Причины такого подхода:

1. Модульная архитектура

Каждый компонент развивается отдельно.

2. Минимизация обновлений

Не требуется обновлять всю библиотеку ради одного компонента.

3. Изолированные изменения

Обновления не распространяются на другие компоненты.

Совместимость между пакетами

Несмотря на независимое версионирование, большинство пакетов Radix UI используют общие внутренние зависимости:

  • @radix-ui/react-primitive
  • @radix-ui/react-compose-refs
  • @radix-ui/react-context
  • @radix-ui/react-id

Эти пакеты обеспечивают базовую инфраструктуру компонентов.

При обновлении одного компонента npm автоматически разрешает совместимые версии этих внутренних зависимостей.

Peer Dependencies

Некоторые пакеты Radix UI используют peerDependencies, главным образом для React.

Типичный пример:

"peerDependencies": {
  "react": "^16.8 || ^17 || ^18",
  "react-dom": "^16.8 || ^17 || ^18"
}

Это означает:

  • Radix UI не устанавливает React самостоятельно
  • используется React, установленный в основном проекте
  • версии должны удовлетворять диапазону peerDependencies

Причины использования peerDependencies:

1. предотвращение дублирования React

Несколько копий React в приложении приводят к ошибкам.

2. уменьшение размера node_modules

React используется совместно.

3. гарантированная совместимость контекста React

Контексты должны работать в рамках одной версии React.

Поддерживаемые версии React

Radix UI ориентирован на современную экосистему React.

Минимальные требования обычно включают:

React >= 16.8

Причина — использование React Hooks, которые появились в версии 16.8.

Современные версии библиотек полностью совместимы с:

  • React 17
  • React 18

В React 18 библиотека корректно работает с:

  • Concurrent rendering
  • StrictMode
  • Automatic batching

Совместимость с TypeScript

Radix UI полностью написан на TypeScript и поставляется с типами.

Пакеты включают:

*.d.ts

Типы распространяются вместе с библиотекой и не требуют установки @types.

Совместимость типов зависит от версии TypeScript, используемой в проекте. Обычно поддерживаются версии:

TypeScript >= 4.x

Проблемы совместимости могут возникать при использовании очень старых версий TypeScript, например:

  • несовместимость generic-типов
  • проблемы с conditional types
  • ошибки при работе с JSX types

Version Range в package.json

В проектах чаще всего используется диапазон версий:

^1.0.0

Символ ^ означает:

>=1.0.0 <2.0.0

Таким образом автоматически устанавливаются:

  • все minor-обновления
  • все patch-обновления

Но не устанавливаются major-обновления, которые могут ломать API.

Пример:

"@radix-ui/react-dialog": "^1.0.5"

Допустимые версии:

1.0.6
1.1.0
1.4.2

Недопустимые:

2.0.0

Lock-файлы и фиксация зависимостей

Для стабильности сборки используются lock-файлы:

  • package-lock.json
  • yarn.lock
  • pnpm-lock.yaml

Они фиксируют точные версии установленных пакетов.

Это важно для Radix UI, поскольку minor-обновления могут содержать:

  • улучшения accessibility
  • изменение внутренней логики
  • исправления поведения

Lock-файл гарантирует, что у всех разработчиков используется одинаковая версия.

Обновление версий Radix UI

Обновление выполняется стандартными инструментами npm.

Обновление одного пакета:

npm update @radix-ui/react-dialog

Установка последней версии:

npm install @radix-ui/react-dialog@latest

Для проверки доступных обновлений используется:

npm outdated

Пример результата:

Package                     Current   Wanted   Latest
@radix-ui/react-dialog      1.0.2     1.0.5    2.0.0

Значения:

  • Current — установленная версия
  • Wanted — версия, соответствующая диапазону package.json
  • Latest — последняя опубликованная версия

Миграции между major-версиями

Переход между major-версиями требует анализа изменений.

Основные источники информации:

  • release notes
  • changelog
  • migration guide

Типичные изменения:

Изменение props

Старый API:

<Dialog open={isOpen} onOpenCha nge={setIsOpen} />

Новый API может вводить дополнительные параметры или менять поведение.

Изменение структуры компонентов

Некоторые компоненты Radix UI используют compound pattern.

Пример:

<Dialog.Root>
  <Dialog.Trigger />
  <Dialog.Content />
</Dialog.Root>

В новой версии могут появляться новые элементы:

  • Dialog.Portal
  • Dialog.Close
  • Dialog.Description

Изменение accessibility поведения

Radix UI уделяет большое внимание ARIA-совместимости.

Поэтому major-обновления иногда меняют:

  • фокус-менеджмент
  • keyboard navigation
  • aria-атрибуты

Такие изменения улучшают доступность, но могут менять поведение компонентов.

Совместимость с Next.js

Radix UI корректно работает с популярными фреймворками React.

В частности:

Next.js

Основные требования:

  • поддержка SSR
  • корректная работа порталов
  • отсутствие зависимостей от browser-only API

Radix UI реализует компоненты так, чтобы они безопасно работали в среде серверного рендеринга.

Например, порталы создаются только после монтирования компонента.

Совместимость с системами сборки

Radix UI распространяется в формате:

  • ESM
  • CJS

Это обеспечивает совместимость с большинством инструментов сборки:

  • Vite
  • Webpack
  • Rollup
  • Turbopack
  • Parcel

Пакеты обычно содержат:

dist/index.js
dist/index.mjs
dist/index.d.ts

Это позволяет:

  • использовать tree-shaking
  • уменьшать размер итогового bundle

Tree-Shaking и влияние версий

Radix UI проектировался для эффективного tree-shaking.

Это означает:

в итоговый bundle попадают только используемые компоненты.

Пример:

import * as Dialog from "@radix-ui/react-dialog"

Если используется только:

Dialog.Root
Dialog.Trigger
Dialog.Content

то остальные элементы не включаются в финальный bundle.

Minor-обновления иногда улучшают tree-shaking за счёт:

  • оптимизации экспортов
  • улучшения структуры модулей

Стратегии управления версиями в крупных проектах

В больших приложениях используются дополнительные стратегии контроля версий.

1. Fixed version

Жёсткая фиксация версии:

"@radix-ui/react-dialog": "1.0.5"

Обновления происходят только вручную.

2. Caret range

Наиболее распространённый вариант:

"^1.0.5"

Автоматически применяются безопасные обновления.

3. Renovate / Dependabot

Автоматические системы обновления зависимостей создают pull request при выходе новых версий.

Это позволяет:

  • контролировать обновления
  • автоматически запускать тесты
  • быстро применять исправления безопасности

Обратная совместимость API

Команда Radix UI старается максимально сохранять обратную совместимость.

Основные принципы:

1. стабильный API

breaking-changes происходят редко.

2. предварительные предупреждения

устаревшие функции помечаются как deprecated.

3. подробные changelog

каждое изменение документируется.

Проверка совместимости перед обновлением

Перед обновлением major-версии рекомендуется:

  1. проверить changelog
  2. обновить зависимости в отдельной ветке
  3. запустить unit-тесты
  4. протестировать accessibility
  5. проверить keyboard navigation

Особенно это важно для компонентов:

  • Dialog
  • DropdownMenu
  • Popover
  • Tooltip

Поскольку они активно управляют фокусом и взаимодействием пользователя.

Оглавление