Поле targets в package.json

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

Parcel рассматривает проект как набор целей (targets), каждая из которых описывает конечный результат компиляции: браузерное приложение, Node.js-библиотеку, сервисный бандл или набор статических файлов.

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

Поле targets размещается в package.json и представляет собой объект, где ключ — это имя цели, а значение — конфигурация сборки.

{
  "targets": {
    "default": {
      "context": "browser",
      "distDir": "dist",
      "sourceMap": true
    }
  }
}

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

Значение default target

default — это стандартная цель сборки, используемая, если не указано иное.

Особенности:

  • применяется автоматически при запуске сборки без дополнительных параметров
  • используется как fallback для всех entry points
  • задаёт базовое окружение выполнения
{
  "targets": {
    "default": {
      "context": "browser"
    }
  }
}

Параметр context

context определяет среду выполнения, для которой собирается код.

Основные значения:

  • browser — сборка для веб-приложений
  • node — сборка для Node.js
  • web-worker — для Web Workers
  • electron-renderer — для Electron renderer процесса
  • electron-main — для Electron main процесса
{
  "targets": {
    "server": {
      "context": "node"
    }
  }
}

В зависимости от контекста Parcel:

  • заменяет встроенные модули
  • применяет разные стратегии бандлинга
  • управляет polyfill-ами

Параметр distDir

distDir определяет директорию, куда будут помещены результаты сборки.

{
  "targets": {
    "default": {
      "distDir": "build"
    }
  }
}

Особенности:

  • поддерживает относительные пути
  • может быть различным для разных targets
  • влияет на структуру выходного проекта

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

Параметр sourceMap

sourceMap управляет генерацией карт исходного кода.

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

  • true — включить source maps
  • false — отключить
  • "inline" — встроенные карты
  • "hidden" — карты генерируются, но не подключаются к output
{
  "targets": {
    "default": {
      "sourceMap": true
    }
  }
}

Source maps используются для:

  • отладки в браузере
  • анализа ошибок в runtime
  • восстановления оригинального кода из минифицированного

Параметр engines

engines задаёт требования к среде выполнения, включая версии браузеров или Node.js.

{
  "targets": {
    "default": {
      "engines": {
        "browsers": "> 0.5%, last 2 versions",
        "node": ">=16"
      }
    }
  }
}

Parcel использует эту информацию для:

  • выбора уровня транспиляции
  • добавления или исключения polyfill-ов
  • оптимизации output под конкретные окружения

Параметр outputFormat

outputFormat определяет формат выходного бандла.

Основные варианты:

  • global — UMD-подобный формат
  • esmodule — ES Modules
  • commonjs — CommonJS
  • commonjs-esmodule — гибридный формат
{
  "targets": {
    "library": {
      "outputFormat": "esmodule"
    }
  }
}

Выбор формата влияет на:

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

Параметр isLibrary

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

{
  "targets": {
    "default": {
      "isLibrary": true
    }
  }
}

При включении:

  • Parcel оптимизирует экспортируемые модули
  • сохраняется структура API
  • активируется более агрессивный tree-shaking

Параметр includeNodeModules

includeNodeModules управляет тем, будут ли зависимости из node_modules включены в бандл.

{
  "targets": {
    "default": {
      "includeNodeModules": false
    }
  }
}

Варианты поведения:

  • true — включать все зависимости
  • false — исключать зависимости (external)
  • объект с правилами включения/исключения

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

Несколько targets в одном проекте

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

{
  "targets": {
    "app": {
      "context": "browser",
      "distDir": "dist/app"
    },
    "server": {
      "context": "node",
      "distDir": "dist/server"
    }
  }
}

Такой подход применяется в архитектурах:

  • универсальных приложений (SSR)
  • монорепозиториев
  • библиотек с несколькими форматами вывода

Наследование и переопределение настроек

Parcel использует модель частичного наследования:

  • общие настройки могут быть заданы на уровне default
  • специфичные targets переопределяют отдельные поля
  • отсутствующие параметры наследуются автоматически
{
  "targets": {
    "default": {
      "context": "browser",
      "sourceMap": true
    },
    "legacy": {
      "engines": {
        "browsers": "> 1%"
      }
    }
  }
}

Связь с entry points

Targets могут быть связаны с конкретными входными файлами через package.json или CLI-конфигурацию Parcel.

Parcel сопоставляет:

  • entry point
  • target
  • output directory

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

Поведение при отсутствии targets

Если поле targets не задано, Parcel использует автоматические значения:

  • context: browser
  • стандартный distDir
  • базовые настройки совместимости

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

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

Часто встречающиеся проблемы:

  • несоответствие context реальной среде выполнения
  • конфликт outputFormat и isLibrary
  • неправильное разделение distDir для разных targets
  • отсутствие engines, приводящее к избыточной транспиляции

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

Роль targets в архитектуре сборки Parcel

Механизм targets формирует абстракцию уровня сборки, отделяя:

  • исходный код
  • правила трансформации
  • выходные артефакты

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

Оглавление