Конфигурационный файл rollup.config.js

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

На практике используется файл rollup.config.js в корне проекта, хотя допустимы и другие варианты: rollup.config.mjs, rollup.config.cjs, либо экспорт конфигурации из TypeScript при наличии соответствующего плагина.

Базовая форма конфигурации

Конфигурация может экспортироваться через export default или module.exports:

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

или в CommonJS-формате:

module.exports = {
  input: 'src/index.js',
  output: {
    file: 'dist/bundle.js',
    format: 'esm'
  }
}

Разница определяется режимом работы Node.js и типом проекта (type: module в package.json).

Параметр input

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

input: 'src/main.js'

Допускается указание нескольких точек входа:

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

В этом случае формируется несколько бандлов, каждый со своей точкой входа.

Параметр output

output определяет результат сборки. Это может быть объект или массив объектов.

Основные свойства:

  • file — путь к итоговому файлу
  • dir — директория вывода (для множественных бандлов)
  • format — формат модуля
  • name — глобальное имя для IIFE или UMD
  • sourcemap — генерация source map

Пример:

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

Форматы модулей

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

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

Пример UMD:

output: {
  file: 'dist/library.js',
  format: 'umd',
  name: 'MyLibrary'
}

Плагины и система расширения

Rollup изначально работает только с ES-модулями. Поддержка дополнительных возможностей реализуется через плагины.

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

export default {
  input: 'src/index.js',
  output: {
    file: 'dist/bundle.js',
    format: 'esm'
  },
  plugins: [
    resolve(),
    commonjs()
  ]
}

Порядок подключения плагинов критичен: каждый следующий плагин получает результат предыдущего.

Конфигурация с внешними зависимостями

Параметр external исключает модули из бандла.

external: ['react', 'react-dom']

Также допускается функция:

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

Это используется для исключения встроенных модулей Node.js или peerDependencies.

Настройка treeshaking

Rollup применяет tree-shaking автоматически, но поведение можно регулировать:

treeshake: {
  moduleSideEffects: false,
  propertyReadSideEffects: false
}

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

Несколько конфигураций в одном файле

Файл может экспортировать массив конфигураций:

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

Каждый объект выполняется как отдельная сборка.

Асинхронная конфигурация

Конфигурация может быть функцией, возвращающей Promise:

export default async () => {
  const pkg = await import('./package.json', { assert: { type: 'json' } })

  return {
    input: 'src/index.js',
    output: {
      file: pkg.default.main,
      format: 'esm'
    }
  }
}

Это позволяет динамически определять параметры сборки.

Условная конфигурация

Конфигурация может зависеть от CLI-параметров:

export default commandLineArgs => {
  const production = commandLineArgs.production

  return {
    input: 'src/index.js',
    output: {
      file: production ? 'dist/app.min.js' : 'dist/app.js',
      format: 'esm'
    }
  }
}

Запуск:

rollup -c --production

Работа с watch-режимом

Rollup поддерживает наблюдение за изменениями файлов:

export default {
  input: 'src/index.js',
  output: {
    file: 'dist/bundle.js',
    format: 'esm'
  },
  watch: {
    include: 'src/**',
    exclude: 'node_modules/**'
  }
}

Watch-режим используется в разработке и позволяет автоматически пересобирать проект.

Экспорт внешних модулей и peer dependencies

Для библиотек важно не включать зависимости в бандл:

import pkg from './package.json'

export default {
  input: 'src/index.js',
  external: Object.keys(pkg.peerDependencies || {}),
  output: {
    file: 'dist/index.js',
    format: 'esm'
  }
}

Это обеспечивает корректное использование библиотеки в чужих проектах.

Несколько выходов (multi-format build)

Типичная конфигурация библиотеки:

export default {
  input: 'src/index.js',
  external: ['react'],
  output: [
    {
      file: 'dist/index.esm.js',
      format: 'esm'
    },
    {
      file: 'dist/index.cjs.js',
      format: 'cjs'
    },
    {
      file: 'dist/index.umd.js',
      format: 'umd',
      name: 'Lib'
    }
  ]
}

Такой подход обеспечивает поддержку разных окружений.

Использование функций в output

output может быть функцией, возвращающей объект:

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

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

Плагины и порядок выполнения

Плагины работают как цепочка трансформаций:

  • resolve определяет пути модулей
  • commonjs преобразует CJS в ESM
  • babel транспилирует код
  • terser минифицирует результат
plugins: [
  resolve(),
  commonjs(),
  babel({ babelHelpers: 'bundled' }),
  terser()
]

Нарушение порядка часто приводит к ошибкам сборки или некорректному результату.

Environment variables и режимы сборки

Переменные окружения часто используются для переключения логики:

const dev = process.env.NODE_ENV !== 'production'

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

Rollup не управляет env напрямую, но конфигурация может использовать Node.js API.

Динамическое управление external и plugins

Конфигурация может полностью строиться программно:

export default ({ watch }) => {
  const isWatch = Boolean(watch)

  return {
    input: 'src/index.js',
    plugins: isWatch ? [] : [],
    output: {
      file: 'dist/bundle.js',
      format: 'esm'
    }
  }
}

Особенности использования в монорепозиториях

В монорепозиториях конфигурация часто строится с учетом пакетов:

import path from 'path'

export default {
  input: path.resolve(__dirname, 'packages/core/src/index.js'),
  output: {
    dir: 'packages/core/dist',
    format: 'esm'
  }
}

Часто используется автоматическое определение входов через файловую систему.

CLI и переопределение конфигурации

Параметры CLI могут переопределять конфигурацию:

rollup -c --file dist/output.js --format cjs

Эти значения могут быть доступны через аргументы функции конфигурации.

Типовые ошибки конфигурации

Неправильная настройка часто связана с:

  • отсутствием external для peerDependencies
  • неверным порядком плагинов
  • конфликтом input и output.dir
  • использованием CJS-плагинов в ESM-проекте без совместимости
  • отсутствием name в UMD-сборке

Каждая из этих проблем проявляется на этапе построения графа модулей или генерации бандла, а не во время выполнения приложения.

Оглавление