this.warn и this.error

В архитектуре Rollup плагины работают через единый объект контекста, который передаётся в хуки и предоставляет набор служебных методов. Среди них особое значение имеют механизмы диагностики — this.warn и this.error, через которые формируется обратная связь о проблемах во время сборки. Эти методы не просто выводят сообщения, а интегрируются в систему логирования и управления процессом бандлинга.

Контекст выполнения и привязка this

В хуках Rollup (например, resolveId, load, transform, generateBundle) значение this указывает на PluginContext. Именно этот объект предоставляет доступ к:

  • логированию (warn, error, info)
  • созданию ассетов (emitFile)
  • работе с модулем (getModuleInfo, getModuleIds)
  • управлению разрешением импортов

Важно, что this.warn и this.error доступны только в контексте выполнения плагина. Вне хуков они недоступны и не могут быть вызваны.

this.warn: предупреждения без остановки сборки

Метод this.warn используется для сигнализации о потенциальной проблеме, которая не препятствует продолжению сборки.

Основное поведение

  • сборка не прерывается
  • предупреждение попадает в список diagnostic messages Rollup
  • может быть выведено в консоль или обработано через onLog
  • может быть подавлено через конфигурацию onwarn

Сигнатура

this.warn(messageOrWarning);

Где messageOrWarning может быть:

  • строкой
  • объектом с расширенной информацией

Простой пример

export default function myPlugin() {
  return {
    name: 'my-plugin',
    transform(code, id) {
      if (code.includes('eval(')) {
        this.warn(`Использование eval в модуле ${id} нежелательно`);
      }

      return code;
    }
  };
}

В этом случае сборка продолжится, но разработчик получит сигнал о потенциально опасной конструкции.

Объектное предупреждение

Rollup позволяет передавать структурированные предупреждения:

this.warn({
  message: 'Неиспользуемая переменная',
  code: 'UNUSED_VARIABLE',
  id,
  frame: code.slice(0, 100),
  loc: {
    file: id,
    line: 10,
    column: 5
  }
});

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

Поведение и управление через onwarn

Rollup позволяет централизованно обрабатывать предупреждения:

export default {
  onwarn(warning, warn) {
    if (warning.code === 'CIRCULAR_DEPENDENCY') return;

    warn(warning);
  }
};

Таким образом this.warn становится частью общей системы контроля качества сборки, а не просто выводом сообщений.

Типичные сценарии использования this.warn

  • устаревшие API в коде проекта
  • потенциально небезопасные конструкции (eval, new Function)
  • неэффективные импорты
  • подозрительные зависимости
  • несовместимость с режимом production

this.error: остановка сборки с исключением

В отличие от предупреждений, this.error предназначен для критических ситуаций, при которых продолжение сборки невозможно или недопустимо.

Поведение

  • немедленно прерывает выполнение сборки
  • выбрасывает исключение внутри Rollup pipeline
  • форматирует ошибку через систему диагностики Rollup
  • может быть перехвачен внешними обработчиками, но обычно завершает процесс

Сигнатура

this.error(messageOrError);

Пример с простой строкой

export default function myPlugin() {
  return {
    name: 'my-plugin',
    load(id) {
      if (id.includes('forbidden')) {
        this.error(`Импорт запрещён: ${id}`);
      }
    }
  };
}

При попадании в условие сборка немедленно остановится.

Структурированная ошибка

this.error({
  message: 'Синтаксическая ошибка в конфигурации',
  id,
  frame: code,
  loc: {
    line: 22,
    column: 8
  }
});

Такой формат полезен для интеграции с редакторами и инструментами анализа кода.

Различие между throw и this.error

Внутри плагина можно использовать обычный throw, однако this.error предпочтительнее:

throw new Error()

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

this.error()

  • интегрируется с системой Rollup
  • добавляет id, plugin и позицию
  • формирует стандартизированное сообщение

Важный нюанс: прекращение выполнения

После вызова this.error выполнение текущего хука прекращается:

transform(code, id) {
  this.error('Ошибка');
  return code; // этот код никогда не выполнится
}

Это важно учитывать при проектировании логики плагина.

Ошибки с контекстом модуля

Rollup старается обогащать ошибки информацией о модуле:

  • id — путь к файлу
  • plugin — имя плагина
  • frame — фрагмент исходного кода
  • loc — позиция в файле

Это делает this.error ключевым инструментом диагностики в сложных сборках.

Комбинирование warn и error

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

transform(code, id) {
  if (code.includes('console.log')) {
    this.warn({
      message: 'Найден console.log',
      id
    });
  }

  if (!code.includes('export')) {
    this.error({
      message: 'Модуль должен содержать export',
      id
    });
  }

  return code;
}

Здесь предупреждение сигнализирует о стиле кода, а ошибка блокирует некорректный модуль.

Поведение в разных фазах сборки

this.warn и this.error могут использоваться практически во всех этапах:

  • buildStart
  • resolveId
  • load
  • transform
  • generateBundle
  • writeBundle

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

Практическая модель применения

В архитектуре плагинов принято разделять:

  • warn — для потенциальных проблем качества
  • error — для нарушений контрактов и невозможных состояний

Такое разделение позволяет:

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

Особенности поведения в асинхронных хуках

В асинхронных функциях:

async transform(code, id) {
  const data = await check(code);

  if (!data.valid) {
    this.error('Некорректный модуль');
  }
}

this.error корректно прерывает асинхронный pipeline, Rollup обрабатывает это как отказ от продолжения текущего модуля.

Контекстные ограничения

Важно учитывать:

  • this.warn и this.error недоступны вне плагина
  • нельзя вызывать их после завершения хука
  • нельзя сохранять this и использовать позже
  • нельзя вызывать их в синхронном коде вне Rollup lifecycle

Влияние на пользовательский CLI вывод

Rollup агрегирует все предупреждения и ошибки:

  • предупреждения группируются
  • ошибки выводятся с приоритетом
  • формат зависит от режима CLI (--silent, --watch)

Таким образом, вызовы this.warn и this.error напрямую формируют пользовательский опыт диагностики сборки.

Оглавление