Тип InputOptions и OutputOptions

Тип InputOptions описывает конфигурацию, с которой Rollup начинает процесс построения графа модулей. Эти параметры определяют, какие исходные файлы считаются точкой входа, как анализируются зависимости, какие плагины участвуют в трансформации кода и каким образом интерпретируются модули на этапе сборки.

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

Общая форма типа InputOptions

Упрощённо структура может быть представлена следующим образом:

interface InputOptions {
  input?: string | string[] | { [entryAlias: string]: string };
  plugins?: Plugin[];
  external?: ExternalOption;
  onwarn?: (warning, warn) => void;

  treeshake?: boolean | TreeshakingOptions;

  context?: string;
  moduleContext?: ((id: string) => string) | Record<string, string>;

  cache?: RollupCache;

  acorn?: any;
  acornInjectPlugins?: Function[];

  preserveEntrySignatures?: 'strict' | 'allow-extension' | 'exports-only' | false;

  shimMissingExports?: boolean;
  inlineDynamicImports?: boolean;

  manualChunks?: never;
}

Несмотря на кажущуюся простоту, этот тип управляет критически важными стадиями анализа исходного кода.

Поле input: точка входа графа модулей

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

Варианты задания input

input: 'src/main.js'

input: ['src/main.js', 'src/admin.js']

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

Поведение при разных формах

string — один бандл
array — несколько независимых entry points
object — именованные чанки (multi-entry build)

Именованный формат влияет на генерацию выходных файлов через OutputOptions.entryFileNames.

plugins: расширение механизма компиляции

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

Роль плагинов

Плагины могут:

трансформировать код (transform)
разрешать импорты (resolveId)
загружать содержимое модулей (load)
генерировать дополнительные чанки (generateBundle)

plugins: [
  resolve(),
  commonjs(),
  typescript()
]

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

external: исключение зависимостей из бандла

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

Форматы external

external: ['react', 'lodash']

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

Поведение

модули помечаются как внешние зависимости
импорт сохраняется в итоговом коде
используется для библиотек и server-side сборок

treeshake: оптимизация удаления неиспользуемого кода

treeshake управляет механизмом tree-shaking — удалением неиспользуемых экспортов.

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

treeshake: true

treeshake: {
  moduleSideEffects: true,
  propertyReadSideEffects: false
}

Влияние на граф модулей

анализ статических импортов
маркировка «dead code»
удаление несвязанных экспортов

Tree-shaking является одной из ключевых оптимизаций Rollup.

context и moduleContext: управление this и окружением модулей

context

Определяет значение this в модулях:

context: 'globalThis'

moduleContext

Позволяет задавать контекст точечно:

moduleContext: (id) => {
  if (id.includes('legacy')) return 'window';
  return 'globalThis';
}

Используется при интеграции старых библиотек, зависящих от глобального контекста.

cache: ускорение инкрементальной сборки

cache сохраняет результаты предыдущего анализа графа модулей.

let cache;

const inputOptions = {
  input: 'src/index.js',
  cache
};

Назначение

ускорение watch-режима
повторное использование AST
оптимизация rebuild-процесса

preserveEntrySignatures: контроль экспорта входных модулей

Управляет тем, как Rollup сохраняет сигнатуру экспортов entry-модулей.

Значения

'strict' — строгая проверка экспортов
'exports-only' — только экспортированные символы
'allow-extension' — допускает расширение сигнатуры
false — отключение контроля

inlineDynamicImports: объединение динамических импортов

Если включено:

inlineDynamicImports: true

Rollup объединяет динамические import() в один бандл, запрещая code-splitting.

Тип OutputOptions: конфигурация результата сборки

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

Общая структура OutputOptions

interface OutputOptions {
  file?: string;
  dir?: string;

  format: 'esm' | 'cjs' | 'iife' | 'umd' | 'system';

  name?: string;
  globals?: Record<string, string>;

  plugins?: Plugin[];

  banner?: string | (() => string);
  footer?: string | (() => string);
  intro?: string | (() => string);
  outro?: string | (() => string);

  sourcemap?: boolean | 'inline' | 'hidden';

  entryFileNames?: string;
  chunkFileNames?: string;
  assetFileNames?: string;

  manualChunks?: Record<string, string[]> | ((id: string) => string);

  exports?: 'auto' | 'named' | 'default' | 'none';

  extend?: boolean;
  externalLiveBindings?: boolean;
  freeze?: boolean;
  interop?: 'auto' | 'esModule' | 'default' | 'compat';
  compact?: boolean;
}

format: ключевой параметр вывода

format определяет модульную систему итогового бандла.

Поддерживаемые форматы

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

Влияние на генерацию кода

Формат определяет:

синтаксис экспортов
способ загрузки модулей
совместимость с окружением исполнения

file и dir: режим вывода

file

Используется для одиночного бандла:

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

dir

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

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

При dir Rollup генерирует набор файлов: chunks, entry и assets.

entryFileNames, chunkFileNames, assetFileNames

Эти параметры управляют именованием выходных файлов.

entryFileNames

entryFileNames: '[name]-[hash].js'

chunkFileNames

chunkFileNames: 'chunks/[name]-[hash].js'

assetFileNames

assetFileNames: 'assets/[name]-[hash][extname]'

Токены шаблонов

[name] — имя модуля
[hash] — хеш содержимого
[extname] — расширение файла

globals: маппинг внешних зависимостей

Используется при umd или iife форматах:

globals: {
  react: 'React',
  lodash: '_'
}

Позволяет связать внешние зависимости с глобальными переменными.

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

Объектный вариант

manualChunks: {
  vendor: ['react', 'react-dom']
}

Функциональный вариант

manualChunks(id) {
  if (id.includes('node_modules')) {
    return 'vendor';
  }
}

Позволяет вручную управлять стратегией code splitting.

exports: контроль экспортной модели

exports: 'named'

Варианты:

auto
named
default
none

Определяет совместимость с различными системами модулей.

interop: взаимодействие ESM и CommonJS

interop: 'auto'

Управляет тем, как Rollup обрабатывает импорт CommonJS в ESM окружении.

sourcemap: карта исходного кода

sourcemap: true