Настройка isLibrary

Работа в режиме библиотечной сборки в Parcel требует понимания того, как инструмент разделяет сценарии приложения и сценарии публикации пакета. В обычном веб-приложении Parcel ориентирован на HTML как точку входа, на автоматическую оптимизацию ассетов и на интеграцию с dev-сервером. В библиотечном режиме поведение меняется: сборщик перестаёт исходить из предположения, что результат будет запускаться как страница, и начинает формировать артефакты, пригодные для установки через npm и использования в других проектах.

Библиотечная сборка в Parcel ориентирована на получение переиспользуемого JavaScript-пакета, который может поставляться в нескольких форматах: ESModules, CommonJS, UMD. В этом режиме важны другие характеристики:

  • отсутствие HTML-ориентированных оптимизаций
  • контроль публичного API
  • предсказуемая структура выходных файлов
  • совместимость с пакетными менеджерами
  • корректная обработка peer dependencies

Флаг isLibrary выступает индикатором того, что сборка предназначена не для браузерного приложения, а для распространения как зависимости.

Конфигурация targets и включение isLibrary

Parcel v2 использует систему targets, которая описывает, как именно должен быть собран каждый выходной артефакт пакета. Библиотечный режим задаётся через конфигурацию цели сборки.

Типичная структура package.json:

{
  "source": "src/index.js",
  "main": "dist/main.cjs",
  "module": "dist/main.mjs",
  "targets": {
    "main": {
      "context": "node",
      "outputFormat": "commonjs",
      "isLibrary": true,
      "distDir": "dist"
    },
    "module": {
      "context": "browser",
      "outputFormat": "esmodule",
      "isLibrary": true,
      "distDir": "dist"
    }
  }
}

Параметр isLibrary указывает Parcel, что:

  • входной файл представляет публичный API пакета
  • необходимо исключить поведение, характерное для SPA
  • требуется корректная генерация экспортов
  • необходимо учитывать ограничения tree-shaking на уровне библиотеки

Влияние isLibrary на поведение сборщика

При включении библиотечного режима меняется внутренняя логика оптимизации.

Изменение модели входной точки

Parcel перестаёт трактовать проект как приложение с HTML entrypoint и переходит к модели модульного графа, где:

  • корневой файл считается экспортным интерфейсом
  • все экспортируемые сущности анализируются статически
  • побочные эффекты отслеживаются более строго

Оптимизация экспортов

В библиотечном режиме Parcel активнее применяет tree-shaking. При isLibrary: true:

  • удаляются неиспользуемые экспортируемые функции
  • сохраняется только публичный API
  • модули с side effects помечаются явно

Это особенно важно для пакетов, где размер конечного bundle критичен.

Отключение HTML-ориентированных сценариев

Parcel в обычном режиме может:

  • генерировать HTML автоматически
  • внедрять script-теги
  • управлять HMR через страницу

В библиотечном режиме эти шаги исключаются. Результатом становятся только JavaScript-файлы и сопутствующие ассеты (CSS, если явно включено).

Структура выходных файлов

Библиотечная сборка с isLibrary формирует более строгую структуру артефактов:

  • отдельный файл для каждого формата (CJS, ESM, UMD)
  • предсказуемые имена выходных файлов
  • отсутствие HTML-обвязки
  • минимизация runtime-обёрток

Пример типичного результата:

dist/
  index.cjs
  index.mjs
  index.umd.js

Parcel автоматически синхронизирует эти файлы с настройками package.json, такими как main, module и browser.

Работа с зависимостями

При библиотечной сборке важную роль играет разделение зависимостей:

  • dependencies включаются в бандл или резолвятся
  • peerDependencies исключаются из финального bundle
  • devDependencies полностью игнорируются

При isLibrary: true Parcel усиливает контроль за корректностью этих границ. Ошибки часто возникают в случаях:

  • импортов dev-зависимостей в публичном API
  • неявного включения больших библиотек в bundle
  • конфликтов между CJS и ESM версиями зависимостей

Output formats и их сочетание

Библиотечный режим почти всегда подразумевает мультиформатный билд.

ESModule

Формат ESModule используется для современных сборщиков:

  • поддерживает tree-shaking на стороне потребителя
  • совместим с Vite, Rollup, Webpack 5+

CommonJS

Формат CommonJS сохраняется для:

  • Node.js окружений
  • старых сборочных систем

UMD

UMD используется для универсального подключения:

  • через <script> тег
  • через AMD loader
  • как fallback-формат

Parcel автоматически адаптирует структуру экспорта под выбранный формат при включённом isLibrary.

Side effects и корректная маркировка модулей

Библиотечная сборка требует точного указания побочных эффектов. В связке с Parcel это влияет на tree-shaking.

В package.json:

{
  "sideEffects": false
}

или более точечно:

{
  "sideEffects": [
    "*.css",
    "./src/polyfills.js"
  ]
}

При isLibrary: true Parcel учитывает эти настройки при построении графа модулей.

Интеграция с CSS и ассетами

Библиотеки часто включают стили. Parcel обрабатывает их следующим образом:

  • CSS может быть инлайнен или вынесен в отдельный файл
  • asset URLs переписываются относительно итогового пакета
  • шрифты и изображения попадают в dist с хешированием

В библиотечном режиме важно контролировать:

  • публичный API стилей
  • конфликт имён классов
  • возможность отключения CSS (через опции или отдельные entrypoints)

TypeScript и декларации типов

Parcel может генерировать сопутствующие .d.ts файлы через плагины или интеграции.

В связке с isLibrary это становится критичным, поскольку:

  • библиотека без типов теряет потребительскую ценность
  • экспорт API должен соответствовать TS-декларациям
  • изменения структуры экспорта должны синхронизироваться с типами

Разделение entrypoints

Библиотека часто содержит несколько точек входа:

  • основной модуль
  • утилиты
  • вспомогательные подмодули

Parcel позволяет описывать это через targets:

{
  "targets": {
    "main": {
      "source": "src/index.js",
      "isLibrary": true
    },
    "utils": {
      "source": "src/utils/index.js",
      "isLibrary": true
    }
  }
}

Каждый target становится отдельным экспортируемым артефактом.

Поведение в режиме разработки

При разработке библиотек Parcel сохраняет:

  • HMR для внутренних модулей
  • быстрый rebuild графа зависимостей
  • изоляцию API от тестового окружения

Однако dev-server в библиотечном режиме не моделирует конечное потребление так же, как в приложении. Основной акцент делается на корректность экспортов, а не на визуальный слой.

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

При использовании isLibrary часто возникают системные ошибки конфигурации:

  • отсутствие явного source
  • смешивание application и library targets
  • неправильный outputFormat для платформы
  • включение HTML entrypoint в библиотечный target

Особенно критична ситуация, когда один и тот же target используется одновременно для приложения и библиотеки — это приводит к непредсказуемому tree-shaking и лишним runtime-обёрткам.

Оптимизация размера пакета

Библиотечный режим усиливает следующие оптимизации:

  • удаление dead code на уровне модулей
  • инлайнинг констант
  • минимизация runtime Parcel
  • устранение дублирующихся зависимостей

Дополнительно важно учитывать:

  • использование ES modules внутри библиотеки
  • избегание динамических require
  • ограничение глобальных побочных эффектов

Взаимодействие с публикацией в npm

Результат сборки с isLibrary обычно напрямую готов к публикации:

  • корректные entrypoints (main, module, exports)
  • предсказуемая структура dist
  • отсутствие dev-артефактов
  • совместимость с Node resolution алгоритмом

Parcel не управляет публикацией, но формирует структуру, которая соответствует ожиданиям npm-экосистемы.

Резюме архитектурного поведения

Режим isLibrary в Parcel меняет не отдельные опции, а модель мышления сборщика:

  • от страницы к модулю
  • от runtime к API
  • от визуальной сборки к контрактной
  • от HMR-ориентации к экспортной стабильности

Именно это делает библиотечную конфигурацию фундаментально отличной от стандартной веб-сборки.

Оглавление