Структура объекта конфигурации

Конфигурационный объект Rollup представляет собой центральную точку описания процесса сборки, в которой фиксируются входные модули, стратегия объединения кода, правила обработки зависимостей, подключаемые плагины и параметры генерации итогового бандла. Его структура формируется как обычный JavaScript-объект с набором строго определённых полей, каждое из которых влияет на отдельный этап пайплайна компиляции.

Основой конфигурации выступает поле входа, определяющее точку начала графа модулей.

Поле input задаёт исходные модули, с которых начинается построение dependency graph. Значение может принимать несколько форматов:

строка с путём к файлу;
массив строк для мульти-энтри сборки;
объект, где ключи определяют имена входных чанков.

Объектная форма используется при необходимости явно задать имена выходных бандлов:

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

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

При использовании массива входов Rollup создаёт несколько независимых точек входа без явной именованной привязки:

export default {
  input: ['src/main.js', 'src/polyfills.js']
}

output: структура выходного бандла

Поле output описывает параметры генерации результирующего кода. Оно может быть объектом либо массивом объектов, что позволяет формировать несколько вариантов сборки за один запуск.

Минимальная структура включает следующие ключевые свойства:

file — путь к итоговому файлу;
dir — директория для чанков при code splitting;
format — формат модуля;
name — глобальное имя для IIFE/UMD сборок.

Базовый пример:

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

Формат output является наиболее насыщенной частью конфигурации, так как включает большое количество дополнительных параметров, влияющих на структуру генерируемого кода.

format: тип модуля

Поле format определяет тип выходного бандла. Основные значения:

esm — ES Modules;
cjs — CommonJS;
iife — самовызывающаяся функция;
umd — универсальный формат.

Выбор формата влияет на синтаксис экспорта, структуру обёртки и поведение в разных средах исполнения.

dir и file: стратегии вывода

Использование file предполагает генерацию единственного файла. В случаях code splitting применяется dir, позволяющий распределять несколько чанков по директории:

export default {
  input: 'src/index.js',
  output: {
    dir: 'dist',
    format: 'esm'
  }
}

При наличии динамических импортов Rollup автоматически формирует дополнительные файлы, размещая их внутри указанной директории.

name: глобальная переменная

Поле name используется в форматах iife и umd, где модуль экспортируется в глобальное пространство:

export default {
  input: 'src/index.js',
  output: {
    file: 'dist/bundle.js',
    format: 'iife',
    name: 'MyLibrary'
  }
}

В этом случае результат оборачивается в функцию, а экспортируемые сущности становятся свойствами глобального объекта.

plugins: расширение пайплайна сборки

Поле plugins представляет собой массив функций-плагинов, каждая из которых вмешивается в определённые этапы обработки модулей. Плагины могут трансформировать код, разрешать импорты, обрабатывать JSON, работать с CSS и выполнять множество других задач.

Структурно поле выглядит следующим образом:

import resolve from '@rollup/plugin-node-resolve'

export default {
  input: 'src/index.js',
  plugins: [
    resolve()
  ]
}

Плагины выполняются последовательно, формируя цепочку трансформаций. Порядок их объявления имеет критическое значение, так как влияет на итоговое дерево модулей и результат компиляции.

external: управление внешними зависимостями

Поле external определяет модули, которые не должны включаться в итоговый бандл. Это важно при работе с библиотеками, зависящими от сторонних пакетов, поставляемых отдельно.

Форма может быть:

строкой;
массивом строк;
функцией, возвращающей boolean.

Пример исключения зависимостей:

export default {
  input: 'src/index.js',
  external: ['react', 'react-dom']
}

Функциональная форма позволяет задавать динамическое правило:

external: id => id.startsWith('lodash')

Такая стратегия полезна при создании библиотек, где важно не дублировать внешние зависимости.

treeshake: управление удалением неиспользуемого кода

Параметр treeshake регулирует алгоритм удаления мёртвого кода. Он может быть булевым значением или объектом с расширенной конфигурацией.

export default {
  treeshake: true
}

При объектной форме доступны более тонкие настройки:

moduleSideEffects — управление побочными эффектами модулей;
propertyReadSideEffects — анализ свойств объектов;
unknownGlobalSideEffects — обработка глобальных переменных.

Эти параметры влияют на агрессивность оптимизации и могут существенно менять итоговый размер бандла.

context: контекст выполнения модулей

Поле context задаёт значение this внутри модулей. По умолчанию используется undefined в строгом режиме, но может быть переопределено:

export default {
  context: 'window'
}

Это поле важно при работе со старыми библиотеками, завязанными на глобальный контекст исполнения.

onwarn: обработка предупреждений

Функция onwarn перехватывает предупреждения сборщика и позволяет модифицировать их поведение. Она принимает объект предупреждения и стандартный обработчик:

export default {
  onwarn(warning, warn) {
    if (warning.code === 'CIRCULAR_DEPENDENCY') return
    warn(warning)
  }
}

Такой механизм используется для подавления несущественных предупреждений или их кастомной обработки в CI-средах.

manualChunks: контроль разбиения кода

Поле manualChunks управляет тем, как Rollup делит код на отдельные чанки при code splitting. Оно может быть объектом или функцией.

Функциональная форма:

export default {
  output: {
    manualChunks(id) {
      if (id.includes('node_modules')) {
        return 'vendor'
      }
    }
  }
}

Такой подход позволяет выделять зависимости в отдельные бандлы и оптимизировать кеширование.

globals: отображение внешних модулей

При использовании форматов umd и iife поле globals задаёт соответствие между внешними модулями и глобальными переменными:

export default {
  external: ['react'],
  output: {
    format: 'umd',
    name: 'App',
    globals: {
      react: 'React'
    }
  }
}

Это необходимо для корректной работы библиотек, подключаемых через CDN или глобальные скрипты.

sourcemap: генерация карт исходников

Параметр sourcemap управляет созданием source maps. Возможные значения:

true — генерация отдельного файла карты;
inline — встроенная карта;
hidden — генерация без ссылки в бандле;
false — отключение.

export default {
  output: {
    sourcemap: true
  }
}

Source maps критически важны для отладки, позволяя восстанавливать исходную структуру кода.

preserveModules: сохранение структуры модулей

Флаг preserveModules изменяет стратегию сборки таким образом, что каждый исходный модуль сохраняется как отдельный файл в выходной директории.

export default {
  input: 'src/index.js',
  output: {
    dir: 'dist',
    format: 'esm',
    preserveModules: true
  }
}

Это используется в библиотеках, где важна модульная гранулярность и возможность tree-shaking на уровне потребителя.

Поля banner и footer добавляют произвольный текст в начало и конец каждого выходного файла:

export default {
  output: {
    banner: '/* build start */',
    footer: '/* build end */'
  }
}

Чаще всего используются для лицензий или служебных комментариев.

interop: взаимодействие модулей

Параметр interop влияет на то, как Rollup обрабатывает взаимодействие между CommonJS и ES Modules. Он регулирует генерацию вспомогательных обёрток и поведение импортов по умолчанию.

Возможные значения:

true — включение интеропа;
false — отключение;
auto — автоматическое определение.

Структурные формы конфигурации

Конфигурационный объект Rollup может быть представлен не только как единичный объект, но и в нескольких альтернативных формах:

Функция, возвращающая объект конфигурации.
Массив объектов для множественных сборок.
Асинхронная функция с возможностью загрузки внешних данных.

Функциональная форма:

export default () => {
  return {
    input: 'src/index.js',
    output: {
      file: 'dist/bundle.js',
      format: 'esm'
    }
  }
}

Массив конфигураций:

export default [
  {
    input: 'src/main.js',
    output: { file: 'dist/main.js', format: 'esm' }
  },
  {
    input: 'src/admin.js',
    output: { file: 'dist/admin.js', format: 'esm' }
  }
]

Такая структура позволяет разделять сборки по целям: библиотека, приложение, тестовая версия, legacy-формат.

Статическая и динамическая конфигурация

Конфигурационный объект может быть полностью статическим или зависеть от окружения. Часто используется параметр process.env для переключения режимов:

export default {
  input: 'src/index.js',
  output: {
    file: process.env.NODE_ENV === 'production'
      ? 'dist/bundle.min.js'
      : 'dist/bundle.js',
    format: 'esm'
  }
}

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

Связь полей конфигурации

Все поля конфигурационного объекта взаимодействуют между собой через единый граф модулей. input определяет начальные точки, plugins изменяют процесс обработки, external исключает зависимости, output формирует итоговую структуру, а treeshake оптимизирует результат. Изменение одного элемента часто влияет на поведение остальных, формируя единый механизм трансформации исходного кода в готовый бандл.

Структура объекта конфигурации

output: структура выходного бандла

format: тип модуля

dir и file: стратегии вывода

name: глобальная переменная

plugins: расширение пайплайна сборки

external: управление внешними зависимостями

treeshake: управление удалением неиспользуемого кода

context: контекст выполнения модулей

onwarn: обработка предупреждений

manualChunks: контроль разбиения кода

globals: отображение внешних модулей

sourcemap: генерация карт исходников

preserveModules: сохранение структуры модулей

banner и footer: обёртка кода

interop: взаимодействие модулей

Структурные формы конфигурации

Статическая и динамическая конфигурация

Связь полей конфигурации