Одноранговые зависимости и удаление неиспользуемого кода

Одноранговые зависимости объявляют пакеты, которые требуются вашей библиотеке, но должны предоставляться пользователем. В package.json вашей библиотеки React должен находиться в peerDependencies, а не в dependencies. При установке библиотеки пользователь npm/yarn не устанавливает React автоматически — в приложении пользователя React уже есть, и ваша библиотека использует тот же экземпляр.

Если React находится в dependencies вашей библиотеки, npm может установить вторую копию React рядом с копией пользователя. Два экземпляра React в одном приложении нарушают работу всех хуков и вызывают ошибку «Invalid hook call». Объявляя React как peerDependency, вы сообщаете npm: «React нужен, но используйте тот экземпляр, который уже есть у пользователя».

Некоторые одноранговые зависимости могут быть необязательными — например, библиотека может поддерживать и styled-components, и CSS Modules. Обозначьте необязательные зависимости с помощью peerDependenciesMeta: { 'styled-components': { optional: true } }. npm не будет предупреждать пользователей об отсутствующих необязательных зависимостях, но типы TypeScript по-прежнему можно предоставить, если необязательный пакет установлен.

Поле sideEffects в package.json сообщает сборщикам, безопасно ли удалять неиспользуемый код вашей библиотеки. Установка "sideEffects": false сообщает webpack, Rollup и подобным инструментам, что импорт любого модуля вашей библиотеки не вызывает побочных эффектов, поэтому все неиспользуемые экспорты можно безопасно удалить из сборки пользователя.

Импорты CSS — распространённый побочный эффект: при импорте они добавляют стили на страницу. Если ваша библиотека импортирует CSS-файлы, задайте "sideEffects": ["*.css", "*.scss"], чтобы сообщить сборщикам: JS-файлы можно безопасно обрабатывать для удаления неиспользуемого кода, но CSS-файлы всегда нужно включать при импорте.

Для максимально эффективного удаления неиспользуемого кода экспортируйте каждый компонент как именованный экспорт из собственного файла. В index.ts повторно экспортируйте всё: export { Button } from './Button'. Если пользователь импортирует только Button, сборщик сможет удалить все остальные компоненты. Файлы-агрегаторы с повторными экспортами позволяют использовать этот подход.

Используйте bundlejs.com, чтобы проверить удаление неиспользуемого кода: вставьте оператор импорта, и сервис сообщит фактический размер сборки. Пакет npm size-limit позволяет задать ограничения размера в package.json и завершить работу CI с ошибкой, если размер импорта превышает ограничение: "size-limit": [{ "path": "dist/index.js", "limit": "10 KB" }].

Задайте бюджет размера для импортов вашей библиотеки. Запускайте npx size-limit в CI, чтобы контролировать его соблюдение. Постепенный рост влияния сборки указывает на расползание области ответственности. В целенаправленной библиотеке компонентов размер импорта отдельного компонента должен составлять не более нескольких килобайт. Предупреждайте о регрессиях до того, как они затронут пользователей.

Избегайте styled-components и Emotion в библиотеках компонентов, которые планируете распространять. Эти решения CSS-in-JS во время выполнения требуют, чтобы пользователь установил ту же библиотеку и версию, что создаёт конфликты одноранговых зависимостей. Даже если пользователь применяет Tailwind или обычный CSS, ему всё равно придётся включить среду выполнения CSS-in-JS в свою сборку. Предпочитайте CSS Modules, которые во время сборки преобразуются в обычный CSS.

CSS Modules хорошо подходят для библиотек в сочетании со сборщиком, который их обрабатывает. tsup и Rollup могут встроить результат CSS Modules в виде имён классов с ограниченной областью действия. Пользователю не нужно ничего настраивать: стили уже изолированы и включены в JS-сборку либо представлены отдельным CSS-файлом, который импортируется.

Ваши инструменты разработки (tsup, TypeScript, библиотеки для тестирования, Storybook) относятся к devDependencies — они нужны только во время разработки и исключаются из установки npm для пользователей. React указывается и в peerDependencies (требование среды выполнения), и в devDependencies (он нужен для локальной компиляции и тестирования библиотеки).

Что сообщает сборщикам установка "sideEffects": false в package.json библиотеки?

Объявляйте React в peerDependencies (а не dependencies), чтобы пользователи использовали экземпляр React из своего приложения. sideEffects: false включает полное удаление неиспользуемого кода вашей библиотеки. Используйте sideEffects: ['*.css'], чтобы защитить импорты CSS от удаления. Именованные экспорты из отдельных файлов обеспечивают максимальную точность удаления неиспользуемого кода. Устанавливайте бюджет размера с помощью size-limit в CI. В библиотеках предпочитайте CSS Modules вместо CSS-in-JS, чтобы избежать конфликтов одноранговых зависимостей.