Налаштування бандлера 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 для десятків бібліотек.