Поле test, exclude, include: фильтрация файлов

В экосистеме SWC фильтрация файлов определяет, какие модули будут обрабатываться трансформацией, а какие будут пропущены. Эти параметры используются как на уровне сборщиков (Webpack, Vite, Rollup-плагины), так и в интеграциях с @swc/core, где логика отбора файлов влияет на производительность и корректность трансформации.

Фильтрация строится вокруг трёх ключевых механизмов: test, include, exclude. Несмотря на схожесть назначения, каждый из них работает в своём контексте и имеет собственную приоритетность.

test: базовое условие применения трансформации

Поле test задаёт условие, при котором файл считается подходящим для обработки SWC. Чаще всего используется в конфигурациях загрузчиков, например в Webpack-правилах. 

module.exports = {
  test: /\.jsx?$/,
  use: {
    loader: "swc-loader",
    options: {
      jsc: {
        parser: {
          syntax: "ecmascript",
          jsx: true
        }
      }
    }
  }
};

test работает как первичный фильтр:

  • обычно принимает RegExp
  • определяет, какие файлы вообще попадают в пайплайн
  • применяется до любых exclude

Типичный сценарий — ограничение обработки только JavaScript/TypeScript файлов: 

test: /\.[cm]?[jt]sx?$/

Это выражение включает:

  • .js
  • .ts
  • .jsx
  • .tsx
  • .mjs
  • .cjs

exclude: исключение из обработки

Поле exclude применяется для явного исключения директорий или файлов, даже если они подходят под test.

Наиболее распространённый кейс — исключение node_modules. 

exclude: /node_modules/

SWC в этом случае полностью пропускает трансформацию зависимостей, что существенно ускоряет сборку.

Более сложные сценарии включают комбинирование исключений: 

exclude: [
  /node_modules/,
  /dist/,
  /build/
]

Поведение:

  • если файл совпадает с exclude, он не обрабатывается
  • exclude имеет приоритет над test

Это важно для случаев, когда test слишком широкий: 

test: /\.[jt]sx?$/,
exclude: /node_modules/

include: ограничение области обработки

Поле include задаёт явное разрешение на обработку файлов внутри определённых директорий. Оно используется как противоположность exclude, но работает как дополнительный слой фильтрации. 

include: /src/

Это означает, что SWC будет обрабатывать только файлы внутри src, даже если test совпадает с более широким набором.

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

include: [
  /packages\/app/,
  /packages\/ui/
]

Взаимодействие test, include и exclude

Логика применения фильтров строится по принципу последовательного отсечения:

  1. Проверка соответствия test
  2. Проверка попадания в include (если задано)
  3. Проверка отсутствия в exclude

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

file проходит, если:
(test совпал) AND (входит в include или include не задан) AND (не входит в exclude)

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

Стандартная конфигурация для приложения 

test: /\.[jt]sx?$/,
exclude: /node_modules/

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

Монорепозиторий с ограничением области 

test: /\.[jt]sx?$/,
include: /packages\/app/,
exclude: /packages\/app\/legacy/

Такой подход позволяет:

  • ускорить сборку
  • изолировать части проекта
  • исключить устаревшие модули

Полная изоляция исходного кода 

include: /src/,
exclude: /src\/vendor/,
test: /\.[jt]sx?$/

Здесь:

  • src/vendor исключается даже внутри src
  • внешние зависимости полностью игнорируются

Форматы значений

Все три поля могут принимать:

  • RegExp
  • массив RegExp
  • иногда строки (в зависимости от интеграции)

Пример массива: 

exclude: [/node_modules/, /coverage/, /dist/]

Особенности поведения в разных интеграциях

SWC Loader (Webpack)

  • test — обязательный фильтр правил Webpack
  • include/exclude — часть правила module.rules
  • применяется до передачи файла в SWC

@swc/core

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

Turbopack / Next.js SWC

  • используется оптимизированная версия фильтрации
  • exclude node_modules часто встроен по умолчанию
  • include применяется для сегментации пакетов

Частые ошибки при настройке фильтрации

Перекрытие include и test 

test: /\.js$/,
include: /src/,

Если src содержит .ts файлы, они будут проигнорированы несмотря на расположение.

Слишком широкий test 

test: /.*/

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

Игнорирование node_modules в больших проектах

Отсутствие: 

exclude: /node_modules/

приводит к:

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

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

При одновременном использовании всех параметров действует следующая логика: 

1. Проверка test (файл должен быть подходящим)
2. Проверка include (если задан — файл должен входить)
3. Проверка exclude (файл не должен быть исключён)

Любое нарушение условий завершает обработку файла без передачи в SWC.

Роль фильтрации в производительности

Фильтрация напрямую влияет на:

  • время компиляции
  • нагрузку на CPU
  • объем памяти
  • кеширование трансформаций

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

Дополнительное использование include позволяет сузить область работы SWC до минимально необходимого набора исходников, что особенно критично в крупных кодовых базах и монорепозиториях.

Оглавление