Сборка библиотек с Rollup и tsup

Конфигурация Vite по умолчанию оптимизирована для приложений: она объединяет всё в один пакет, обрабатывает ресурсы и создаёт index.html. Для библиотеки компонентов нужен другой результат: чистые файлы JavaScript в форматах ESM/CJS без накладных расходов во время выполнения, без включённого React и с корректными декларациями TypeScript. Режим библиотеки Vite работает, но Rollup и tsup лучше подходят для этой задачи.

Rollup уже много лет является стандартным сборщиком для библиотек JavaScript. Он создаёт чистый эффективный результат с отличным удалением неиспользуемого кода и поддерживает оба формата вывода: ESM и CJS. Подъём области видимости модулей в Rollup устраняет накладные расходы оболочек модулей, создавая максимально компактные пакеты библиотеки.

tsup — сборщик TypeScript без настройки, работающий на основе esbuild. Он значительно быстрее Rollup (esbuild компилирует за микросекунды, а не за миллисекунды). Минимальная конфигурация: { entry: ['src/index.ts'], format: ['esm', 'cjs'], dts: true } автоматически создаёт оба формата модулей и декларации TypeScript.

Основные параметры tsup: точки входа — массив файлов, служащих точками входа. формат задаёт форматы выходных файлов: ['esm', 'cjs']. генерация деклараций типов создаёт файлы деклараций TypeScript .d.ts рядом с результатом в JS. целевая среда задаёт минимальное окружение JavaScript (esnext или es2020). разбиение отключено оставляет результат в отдельных файлах.

esbuild (через tsup) компилирует в 10–100 раз быстрее, чем Rollup. Rollup создаёт немного более оптимизированный вывод, обеспечивая более точное удаление неиспользуемого кода и больший контроль над границами фрагментов. Для большинства библиотек компонентов скорость tsup выигрывает при разработке. Если нужен максимальный контроль над удалением неиспользуемого кода или сложные настройки с несколькими точками входа, предпочтителен Rollup.

Самая важная настройка сборщика для библиотеки React: никогда не включайте React или ReactDOM в сборку. Пометьте их как внешние зависимости, чтобы они не попали в вывод. Если ваша библиотека включает React в сборку, у пользователей окажутся две копии React — одна из вашей сборки, а другая из их приложения. Это нарушает работу всех хуков React из-за нескольких экземпляров React.

В конфигурации tsup используйте опцию external: external: ['react', 'react-dom']. В конфигурации Rollup задайте external: ['react', 'react-dom', 'react/jsx-runtime']. Добавьте react/jsx-runtime, если ваша библиотека использует преобразование JSX. Также пометьте внешними все остальные одноранговые зависимости, объявленные вашей библиотекой.

Для минимальной конфигурации Rollup библиотеки TypeScript требуются три плагина: @rollup/plugin-typescript для компиляции TypeScript, @rollup/plugin-node-resolve для разрешения импортов из node_modules и @rollup/plugin-commonjs для преобразования зависимостей CommonJS в ESM в составе сборки. Для файлов объявлений добавьте rollup-plugin-dts.

Типичный вывод библиотеки в двух форматах: dist/esm/index.js и dist/esm/index.d.ts для пользователей ESM, а также dist/cjs/index.js и dist/cjs/index.cjs для пользователей CJS. Поле экспорта в package.json сопоставляет эти пути с соответствующими средами. Файлы объявлений TypeScript находятся рядом с соответствующими файлами JS.

Большим библиотекам полезно иметь несколько точек входа, чтобы пользователи импортировали только необходимое. Например: entry: ['src/index.ts', 'src/utils.ts', 'src/hooks.ts']. Для каждой точки входа создаются собственные файлы вывода. Поле экспорта в package.json сопоставляет каждый общедоступный путь с его выводом: './utils' → './dist/utils.js'.

Добавьте команду сборки в скрипты package.json: "build": "tsup". tsup читает конфигурацию из tsup.config.ts в корневом каталоге. Скрипт предварительной публикации должен запускать сборку: "prepublishOnly": "npm run build" гарантирует, что перед публикацией в npm ваш пакет всегда будет собран.

Почему при сборке библиотеки компонентов React необходимо помечать как внешнюю зависимость?

tsup на основе esbuild обеспечивает быструю сборку без конфигурации с параметром format: ['esm', 'cjs'] и параметром dts: true. Rollup предоставляет более точный контроль над удалением неиспользуемого кода с помощью @rollup/plugin-typescript. Критическое правило: всегда помечайте react, react-dom и все одноранговые зависимости как внешние, чтобы не включать их в сборку. Выпускайте результат в dist/esm/ и dist/cjs/ вместе с параллельными объявлениями TypeScript. Несколько точек входа позволяют пользователям выполнять более точное удаление неиспользуемого кода.