Установка и первый запуск

Сборщик Rollup применяется для объединения модулей JavaScript в единый пакет или набор пакетов. Основная область применения — библиотеки, SDK, инструменты и проекты, ориентированные на современный формат ES Modules.

После установки Rollup проект получает:

  • поддержку модульной архитектуры;
  • автоматическое объединение импортов;
  • tree-shaking для удаления неиспользуемого кода;
  • генерацию различных форматов сборки;
  • систему плагинов;
  • поддержку TypeScript, Babel, PostCSS и других инструментов.

Rollup отличается минималистичным подходом. Базовая установка содержит только ядро сборщика, а расширение функциональности выполняется через плагины.

Проверка окружения

Перед установкой требуется наличие Node.js.

Проверка версии Node.js:

node -v

Проверка npm:

npm -v

Rollup ориентирован на современное окружение Node.js. На практике рекомендуется использовать актуальные LTS-версии.

Инициализация проекта

Создание новой директории:

mkdir rollup-project

Переход в папку проекта:

cd rollup-project

Инициализация package.json:

npm init -y

После выполнения команды создаётся файл:

{
  "name": "rollup-project",
  "version": "1.0.0",
  "main": "index.js",
  "license": "ISC"
}

Файл package.json становится центральной точкой конфигурации npm-пакета и зависимостей.

Установка Rollup

Локальная установка

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

npm install --save-dev rollup

После установки Rollup попадает в раздел devDependencies:

{
  "devDependencies": {
    "rollup": "^4.0.0"
  }
}

Локальная установка считается правильным подходом, поскольку:

  • версии фиксируются внутри проекта;
  • исключаются конфликты между проектами;
  • обеспечивается воспроизводимость сборки;
  • CI/CD использует одинаковые версии инструментов.

Проверка установки

Проверка установленной версии:

npx rollup --version

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

rollup v4.18.0

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

Структура первого проекта

Минимальная структура проекта:

rollup-project/
├── node_modules/
├── src/
│   ├── main.js
│   └── math.js
├── dist/
├── package.json
└── rollup.config.js

Назначение каталогов:

Каталог Назначение
src Исходный код
dist Готовая сборка
node_modules Установленные зависимости

Создание первого модуля

Файл:

src/math.js

Содержимое:

export function sum(a, b) {
    return a + b;
}

Модуль экспортирует функцию через ES Modules.

Создание точки входа

Файл:

src/main.js

Содержимое:

import { sum } from './math.js';

const result = sum(5, 10);

console.log(result);

Rollup анализирует граф импортов, начиная с точки входа.

Первый запуск без конфигурации

Rollup может запускаться напрямую из командной строки.

Простейшая команда сборки:

npx rollup src/main.js --file dist/bundle.js --format iife

Разбор параметров:

Параметр Назначение
src/main.js Точка входа
–file Имя выходного файла
–format Формат сборки

Форматы сборки

Rollup поддерживает несколько форматов вывода.

iife

--format iife

Immediately Invoked Function Expression.

Подходит для подключения через <script> в браузере.

Результат:

(function () {
    'use strict';

    function sum(a, b) {
        return a + b;
    }

    const result = sum(5, 10);

    console.log(result);

})();

esm

--format esm

Современный формат ES Modules.

Используется:

  • в браузерах;
  • библиотеках;
  • Vite;
  • современных bundler-системах.

cjs

--format cjs

Формат CommonJS.

Используется преимущественно в Node.js.

umd

--format umd

Universal Module Definition.

Подходит для библиотек, поддерживающих разные среды выполнения.

Создание конфигурационного файла

При усложнении проекта параметры командной строки становятся неудобными.

Создание файла:

rollup.config.js

Содержимое:

export default {
    input: 'src/main.js',

    output: {
        file: 'dist/bundle.js',
        format: 'iife'
    }
};

Первый запуск через конфигурацию

Команда:

npx rollup -c

Флаг -c сообщает Rollup о необходимости использовать файл конфигурации.

Анализ конфигурации

input

input: 'src/main.js'

Определяет точку входа проекта.

Rollup начинает обход импортов именно отсюда.

output

output: {
    file: 'dist/bundle.js',
    format: 'iife'
}

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

file

file: 'dist/bundle.js'

Путь к итоговому файлу.

format

format: 'iife'

Определяет формат генерируемого кода.

Добавление npm-скриптов

Ручной ввод длинных команд быстро становится неудобным.

Раздел scripts:

{
  "scripts": {
    "build": "rollup -c"
  }
}

Запуск сборки:

npm run build

Автоматическая пересборка

Rollup поддерживает watch-режим.

Команда:

npx rollup -c -w

Или через scripts:

{
  "scripts": {
    "dev": "rollup -c -w"
  }
}

Запуск:

npm run dev

После изменения файлов Rollup автоматически пересобирает проект.

Поддержка нескольких выходных форматов

Один из сильных аспектов Rollup — генерация нескольких сборок одновременно.

Пример:

export default {
    input: 'src/main.js',

    output: [
        {
            file: 'dist/bundle.cjs.js',
            format: 'cjs'
        },
        {
            file: 'dist/bundle.esm.js',
            format: 'esm'
        }
    ]
};

Особенно полезно при разработке библиотек.

Использование strict mode

Rollup автоматически добавляет:

'use strict';

Это обеспечивает:

  • более безопасное выполнение кода;
  • запрет опасных конструкций;
  • оптимизации JavaScript-движка.

Tree-shaking при первом запуске

Даже базовая сборка Rollup уже использует tree-shaking.

Пример:

export function used() {
    console.log('used');
}

export function unused() {
    console.log('unused');
}

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

import { used } from './module.js';

Функция unused будет удалена из итогового bundle.

Работа с ES Modules

Rollup максимально эффективен именно с ES Modules.

Рекомендуемый стиль:

export function test() {}

и

import { test } from './test.js';

Использование CommonJS снижает эффективность tree-shaking.

Типичная проблема с import/export

Ошибка:

Cannot use import statement outside a module

Причина — Node.js не считает проект модульным.

Решение:

{
  "type": "module"
}

Добавляется в package.json.

Конфигурация ES Modules для Rollup

Современный Rollup использует ESM-конфигурацию.

Корректный вариант:

export default {
    input: 'src/main.js',
    output: {
        file: 'dist/bundle.js',
        format: 'esm'
    }
};

Старый синтаксис:

module.exports = {}

постепенно теряет актуальность.

Использование .mjs

Иногда конфигурация создаётся как:

rollup.config.mjs

Это явно сообщает Node.js о модульном формате файла.

Генерация sourcemap

Для отладки используется sourcemap.

Конфигурация:

export default {
    input: 'src/main.js',

    output: {
        file: 'dist/bundle.js',
        format: 'esm',
        sourcemap: true
    }
};

После сборки появляется:

bundle.js.map

Это позволяет браузеру связывать итоговый код с исходными файлами.

Настройка выходной директории

Вместо одного файла можно указывать директорию.

Пример:

output: {
    dir: 'dist',
    format: 'esm'
}

Особенно полезно при code splitting.

Разница между file и dir

file

Используется для:

  • одной сборки;
  • одного bundle.

Пример:

file: 'dist/app.js'

dir

Используется для:

  • нескольких chunks;
  • динамических импортов;
  • code splitting.

Пример:

dir: 'dist'

Первый code splitting

Модуль:

export function adminPanel() {
    console.log('admin');
}

Динамический импорт:

import('./admin.js').then(module => {
    module.adminPanel();
});

Rollup создаст отдельный chunk.

Очистка dist перед сборкой

Часто добавляют отдельный скрипт:

{
  "scripts": {
    "clean": "rm -rf dist",
    "build": "rollup -c"
  }
}

В Windows обычно используют:

rimraf dist

Установка rimraf

npm install --save-dev rimraf

Скрипт:

{
  "scripts": {
    "clean": "rimraf dist"
  }
}

Минимальный production-вариант

export default {
    input: 'src/main.js',

    output: {
        file: 'dist/bundle.js',
        format: 'esm',
        sourcemap: false
    }
};

Проверка результата сборки

После запуска:

npm run build

в директории dist появляется готовый bundle.

Пример:

function sum(a, b) {
    return a + b;
}

const result = sum(5, 10);

console.log(result);

Rollup объединяет модули в компактный оптимизированный код.

Типичный жизненный цикл запуска Rollup

1. Чтение точки входа

input: 'src/main.js'

2. Построение графа зависимостей

Rollup анализирует:

import ...

3. Удаление неиспользуемого кода

Активируется tree-shaking.

4. Генерация bundle

Создаётся итоговый файл.

5. Запись результата

Bundle сохраняется в dist.

Наиболее распространённые ошибки

Не найден файл входа

Ошибка:

Could not resolve entry module

Причины:

  • неправильный путь;
  • отсутствует файл;
  • ошибка регистра символов.

Неизвестный формат

Ошибка:

Unknown output format

Причина:

format: 'module'

Правильно:

format: 'esm'

Ошибка ESM-конфигурации

Ошибка:

Unexpected token export

Причина — Node.js работает в CommonJS-режиме.

Решение:

{
  "type": "module"
}

Минимальная рабочая конфигурация

export default {
    input: 'src/main.js',

    output: {
        file: 'dist/bundle.js',
        format: 'esm',
        sourcemap: true
    }
};

Минимальный package.json

{
  "name": "rollup-project",
  "type": "module",

  "scripts": {
    "dev": "rollup -c -w",
    "build": "rollup -c"
  },

  "devDependencies": {
    "rollup": "^4.0.0"
  }
}
Оглавление