Класс Parcel: инициализация и методы

Архитектура класса Parcel в Node API

В Parcel (начиная с версии 2) программный интерфейс сборки предоставляется через пакет @parcel/core, где центральной сущностью выступает класс Parcel. Он инкапсулирует весь процесс бандлинга: от анализа входных точек до генерации выходных ассетов и управления кешированием, трансформациями и графом зависимостей.

Класс проектировался как высокоуровневая обёртка над внутренними этапами пайплайна сборки, предоставляя единый объект для управления жизненным циклом сборки в Node.js окружении.

Импорт и создание экземпляра Parcel

Инициализация начинается с подключения конструктора:

import Parcel from '@parcel/core';

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

const bundler = new Parcel({
  entries: 'src/index.html',
  defaultConfig: '@parcel/config-default',
  mode: 'development',
  shouldDisableCache: false,
  hmrOptions: {
    port: 1234
  }
});

Основные параметры инициализации

entries

Определяет входные точки приложения. Поддерживаются:

  • HTML-файлы
  • JavaScript-файлы
  • TypeScript
  • CSS и другие поддерживаемые форматы
entries: ['src/index.html', 'src/admin.html']

Внутренне Parcel строит граф зависимостей, начиная с этих точек.

defaultConfig

Указывает используемую конфигурацию пайплайна трансформаций.

defaultConfig: '@parcel/config-default'

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

  • трансформеры
  • оптимизаторы
  • резолверы
  • нативные плагины

mode

Режим работы сборщика:

  • development — ускоренная сборка, включён HMR, упрощённая оптимизация
  • production — агрессивная оптимизация, минификация, tree-shaking
mode: 'production'

shouldDisableCache

Управляет использованием кеша Parcel.

shouldDisableCache: true

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

hmrOptions

Конфигурация Hot Module Replacement:

hmrOptions: {
  port: 8080
}

Параметры:

  • port — порт HMR сервера
  • host — хост (опционально)

logLevel

Уровень логирования:

  • none
  • error
  • warn
  • info
  • verbose
logLevel: 'info'

Метод run()

Основной метод запуска одноразовой сборки.

const { bundleGraph, buildTime } = await bundler.run();

Поведение метода

  • строит граф зависимостей
  • выполняет трансформации
  • формирует бандлы
  • возвращает результат сборки

Возвращаемое значение

Объект результата включает:

  • bundleGraph — итоговый граф бандлов
  • buildTime — время сборки
  • changedAssets — изменённые ресурсы

Метод watch()

Запускает режим наблюдения за файлами.

const subscription = await bundler.watch((err, event) => {
  if (err) return console.error(err);

  if (event.type === 'buildSuccess') {
    console.log('Сборка завершена');
  }

  if (event.type === 'buildFailure') {
    console.log('Ошибка сборки');
  }
});

Типы событий

  • buildSuccess — успешная сборка
  • buildFailure — ошибка компиляции
  • buildStart — начало сборки

Подписка и управление

Метод возвращает объект подписки:

await subscription.unsubscribe();

Метод resolve()

Позволяет вручную разрешать модули через резолвер Parcel.

const resolved = await bundler.resolver.resolve({
  specifier: './utils',
  parent: '/src/index.js'
});

Назначение

  • имитация поведения import
  • проверка путей
  • использование внутренних плагинов резолва

Метод build()

Используется как более низкоуровневая альтернатива run().

const result = await bundler.build();

Отличие от run()

  • run() ориентирован на полный жизненный цикл
  • build() используется для явного одноразового запуска без некоторых обёрток событийного уровня

Работа с BundleGraph

После выполнения run() или build() доступен объект BundleGraph.

const bundles = bundleGraph.getBundles();

Основные методы BundleGraph

getBundles()

Возвращает список итоговых бандлов.

bundleGraph.getBundles();
getEntryBundles()

Получение входных бандлов:

bundleGraph.getEntryBundles();
getChildBundles()

Получение зависимых бандлов:

bundleGraph.getChildBundles(bundle);
traverse()

Обход графа зависимостей:

bundleGraph.traverse(node => {
  console.log(node.id);
});

Метод close()

Завершает работу Parcel-инстанса и освобождает ресурсы.

await bundler.close();

Использование

  • остановка watch-режима
  • освобождение файловых watcher’ов
  • очистка памяти кеша в рамках процесса

Событийная модель Parcel

Parcel использует событийный поток внутри методов watch() и run().

Основные события

  • начало сборки
  • успешное завершение
  • ошибка компиляции
  • обновление кеша

Пример обработки:

bundler.watch((err, event) => {
  switch (event.type) {
    case 'buildStart':
      break;
    case 'buildSuccess':
      break;
    case 'buildFailure':
      break;
  }
});

Внутренний жизненный цикл экземпляра Parcel

Экземпляр проходит несколько фаз:

  1. Инициализация конфигурации
  2. Построение резолверов
  3. Создание графа зависимостей
  4. Трансформация модулей
  5. Группировка в бандлы
  6. Оптимизация
  7. Запись результата на диск

Методы класса лишь управляют запуском этих этапов, не реализуя их напрямую.

Особенности состояния экземпляра

Parcel-инстанс сохраняет состояние между сборками:

  • кеш трансформаций
  • граф зависимостей
  • информация о файловой системе
  • результаты HMR

Это позволяет ускорять последующие сборки при использовании watch().

Параллелизм и выполнение

Parcel использует параллельное выполнение задач:

  • трансформации модулей
  • резолв зависимостей
  • оптимизация бандлов

Класс Parcel лишь координирует эти процессы через внутренний планировщик задач.

Работа с ошибками

Ошибки возвращаются через:

  • исключения в run() / build()
  • первый аргумент callback в watch()
bundler.run().catch(err => {
  console.error(err.diagnostics);
});

Объект диагностики содержит:

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

Конфигурационная гибкость экземпляра

Один экземпляр может обслуживать разные сценарии:

  • dev-сервер
  • production сборка
  • CI pipeline
  • тестовые сборки

Поведение меняется через конфигурацию, а не через изменение кода класса.

Интеграция с Node.js окружением

Parcel как класс интегрируется в Node.js процесс:

  • поддержка ESM и CommonJS
  • работа с файловой системой через нативные watcher’ы
  • асинхронные API на Promise
import Parcel from '@parcel/core';

(async () => {
  const bundler = new Parcel({ entries: 'src/index.js' });
  await bundler.run();
})();
Оглавление