Налаштування бандлера Rollup для веб-проекту

Розробляєте npm-пакет або design system? Неправильне налаштування збірника призводить до роздутого бандлу та проблем з tree-shaking. Наша команда з 5-річним досвідом та 50+ проектами на Rollup допомагає налаштувати оптимальний конфіг. За нашими даними, правильно налаштований Rollup скорочує розмір бандлу в середньому на 30–40%. У цій статті розберемо реальні кейси: як підготувати бібліотеку під ESM/CJS/UMD, виключити зайві залежності та автоматизувати CI-збірку. Як зазначається в Документації Rollup, tree-shaking базується на статичному аналізі імпортів — це дозволяє видаляти невикористовуваний код з точністю до символу.

Коли варто вибрати Rollup замість Vite або Webpack?

Rollup не універсальний інструмент. Для SPA з hot reload та dev-сервером зручніше Vite (який сам використовує Rollup всередині для production-збірки). Rollup вибирають, коли потрібно:

• зібрати бібліотеку у форматах ESM + CJS + UMD одночасно
• отримати максимально чистий output без зайвих обгорток
• контролювати, які залежності включаються до бандлу, а які залишаються external
• генерувати TypeScript-декларації поруч із зібраними файлами

Ми переводили проекти, де після заміни Webpack на Rollup розмір підсумкового файлу зменшувався з 200 КБ до 120 КБ, а час збірки скорочувався на 40%.

Встановлення та базовий конфіг

npm install --save-dev rollup @rollup/plugin-node-resolve @rollup/plugin-commonjs @rollup/plugin-typescript rollup-plugin-dts rollup-plugin-postcss @rollup/plugin-url rollup-plugin-visualizer glob 

rollup.config.ts для типової TypeScript-бібліотеки з підтримкою ESM/CJS та декларацій:

import resolve from '@rollup/plugin-node-resolve'; import commonjs from '@rollup/plugin-commonjs'; import typescript from '@rollup/plugin-typescript'; import dts from 'rollup-plugin-dts'; import { defineConfig } from 'rollup'; import pkg from './package.json' assert { type: 'json' }; export default defineConfig([ { input: 'src/index.ts', external: Object.keys(pkg.peerDependencies ?? {}), plugins: [ resolve({ extensions: ['.ts', '.tsx'] }), commonjs(), typescript({ tsconfig: './tsconfig.build.json' }), ], output: [ { file: pkg.module, format: 'esm', sourcemap: true }, { file: pkg.main, format: 'cjs', sourcemap: true, exports: 'named' }, ], }, { input: 'dist/types/index.d.ts', output: { file: 'dist/index.d.ts', format: 'esm' }, plugins: [dts()], }, ]); 

Як правильно оформити exports в package.json?

Сучасний package.json для бібліотеки повинен містити поле exports для чіткого розв'язання модулів. Приклад правильної карти:

Як виключити peer-залежності з бандлу?

Часта помилка — включати React або lodash у бандл бібліотеки. Використовуйте external, який перераховує всі peer-залежності та залежності, які не повинні потрапити до фінального файлу:

const external = [ ...Object.keys(pkg.peerDependencies ?? {}), ...Object.keys(pkg.dependencies ?? {}), ]; // Часткова екстерналізація — виключити тільки частину пакету // external: (id) => id.startsWith('react') || /^lodash/.test(id), 

Як додати CSS та асети?

Для CSS-модулів підключіть rollup-plugin-postcss. Для зображень та SVG — @rollup/plugin-url. Налаштування:

• postcss з modules: true та extract: 'dist/styles.css'
• url з limit: 8192 (inline до 8KB) та destDir: 'dist/assets'

Багатовходова збірка для компонентів

Якщо в бібліотеці кожен компонент імпортується окремо (наприклад, import Button from 'ui/Button'), використовуйте множинні входи з preserveModules:

import { glob } from 'glob'; const entries = Object.fromEntries( (await glob('src/components/**/*.tsx')).map((file) => [ file.replace('src/', '').replace(/\.tsx$/, ''), file, ]) ); export default defineConfig({ input: entries, output: { dir: 'dist', format: 'esm', preserveModules: true, preserveModulesRoot: 'src', }, }); 

preserveModules зберігає структуру директорій, дозволяючи tree-shaking працювати на рівні файлів.

Аналіз розміру бандлу

import { visualizer } from 'rollup-plugin-visualizer'; plugins: [ visualizer({ filename: 'dist/stats.html', gzipSize: true, brotliSize: true, }), ] 

Після збірки відкрийте dist/stats.html — інтерактивне дерево залежностей з реальними розмірами. Концепція tree-shaking — видалення невикористовуваного коду на етапі збірки — тут відображається наочно.

Watch-режим та розробка

Для розробки бібліотеки паралельно з застосунком використовуйте rollup -c --watch або налаштування watch: { include: 'src/**', exclude: 'node_modules/**' }. У монорепозиторії — workspace-посилання.

Кроки налаштування під ключ

1. Аудит існуючої збірки (якщо є) — оцінюємо конфіг та залежності.
2. Проектування карти exports — визначаємо формати та шляхи.
3. Налаштування TypeScript та декларацій — tsconfig, плагіни.
4. Інтеграція CSS та асетів — postcss, url.
5. Оптимізація external-залежностей — виключаємо зайве.
6. Підключення візуалізатора та аналізу — статзбірка.
7. Тестування в CI/CD — гарантія стабільності.

Кожен етап включає перевірку якості: після аудиту ми складаємо звіт з рекомендаціями, після налаштування запускаємо тестову збірку та перевіряємо роботу в CI. Підтримка після впровадження — 1 місяць безкоштовно.

Що входить в результат налаштування?

За підсумками роботи ви отримуєте:

• Робочий конфіг Rollup з плагінами під ваш стек
• Карта exports в package.json для всіх форматів
• TypeScript-декларації (d.ts) поруч із зібраними файлами
• Інтеграція CSS та асетів, якщо потрібно
• Конфігурація CI/CD (GitHub Actions або GitLab CI)
• Звіт з аналізом розміру бандлу (plato, stats.html)
• Консультація щодо використання готової збірки

Чому external dependencies так важливі?

Без правильного external ви ризикуєте включити в бандл цілі фреймворки, наприклад React, що збільшить розмір бібліотеки з 10 КБ до 500+ КБ. Користувачі бібліотеки вже мають ці залежності у своєму проекті — дублювання веде до помилок та роздуття бандлу. Налаштування external з урахуванням peerDependencies та dependencies — обов'язковий крок для будь-якої бібліотеки.

Строки

Гарантія працездатності в CI/CD та підтримка після налаштування. Замовте аудит вашої ручної збірки — ми виявимо вузькі місця та запропонуємо оптимізацію. Отримайте консультацію інженера, який налаштував Rollup для десятків бібліотек.