Компиляция директории

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

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

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

CLI-компиляция директории

Основной сценарий использования реализуется через командную строку: 

swc src -d dist

В этом случае:

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

Расширенный вариант с явным указанием опций: 

swc src --out-dir dist --source-maps

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

Фильтрация файлов

При обходе директории учитываются:

  • расширения файлов (.js, .jsx, .ts, .tsx, .mjs, .cjs)
  • пользовательские include/exclude правила
  • системные исключения (например, node_modules)

Исключение директорий может задаваться через конфигурационный файл: 

{
  "exclude": ["node_modules", "dist"]
}

Подобная фильтрация снижает время компиляции и предотвращает повторную обработку уже сгенерированных артефактов.

Конфигурация через .swcrc

Поведение пакетной компиляции определяется единым конфигурационным файлом .swcrc. Он применяется ко всей директории, если не переопределён локально.

Пример конфигурации: 

{
  "jsc": {
    "parser": {
      "syntax": "typescript",
      "tsx": true
    },
    "target": "es2020"
  },
  "module": {
    "type": "es6"
  },
  "sourceMaps": true
}

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

Сохранение структуры директорий

При компиляции директории сохраняется относительная структура:

Исходное дерево: 

src/
  utils/
    math.ts
  core/
    index.ts

Результат: 

dist/
  utils/
    math.js
  core/
    index.js

Такой подход обеспечивает совместимость с Node.js и ESM/CJS модулями без дополнительных настроек путей.

Режимы обработки модулей

При пакетной компиляции важно учитывать тип модульной системы:

  • ESM (ES Modules)
  • CommonJS
  • гибридные конфигурации

SWC выполняет трансформацию import/export в зависимости от параметра: 

{
  "module": {
    "type": "commonjs"
  }
}

или 

{
  "module": {
    "type": "es6"
  }
}

При обработке директории это правило применяется ко всем файлам одинаково, что обеспечивает консистентность сборки.

Производительность пакетной компиляции

Обработка директорий оптимизирована за счёт нескольких механизмов:

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

В больших проектах (монорепозитории) это позволяет обрабатывать тысячи файлов за секунды.

Инкрементальная компиляция

Хотя базовый режим компиляции директории является статическим, в интеграциях (например, с bundler’ами) возможно использование инкрементального подхода:

  • пересборка только изменённых файлов
  • кэширование AST
  • повторное использование результатов трансформации

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

Работа с вложенными проектами

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

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

Приоритет конфигурации определяется ближайшим файлом .swcrc к обрабатываемому файлу.

Игнорирование и специальные файлы

Помимо явных исключений, SWC автоматически пропускает:

  • временные файлы редакторов
  • скрытые системные каталоги
  • файлы, не соответствующие поддерживаемым расширениям

Дополнительно может использоваться .swcignore, аналогичный .gitignore, для тонкой настройки: 

tests/
*.spec.ts

Это особенно важно при компиляции библиотек, где тестовый код не должен попадать в production-сборку.

Обработка TypeScript в директории

При наличии TypeScript-файлов компиляция директории включает:

  • удаление типов
  • преобразование синтаксиса
  • разрешение JSX (если включено)
  • трансформацию enum, namespace и других конструкций TS

Конфигурация парсера определяет глубину обработки: 

{
  "jsc": {
    "parser": {
      "syntax": "typescript"
    }
  }
}

Генерация source maps при пакетной сборке

Source maps при компиляции директории генерируются для каждого файла отдельно. Это обеспечивает:

  • точную отладку
  • корректную трассировку ошибок
  • интеграцию с браузерными DevTools

Каждый выходной .js файл может иметь соответствующий .map файл.

Особенности обработки JSX

При компиляции директории с React-кодом включается JSX-трансформация: 

{
  "jsc": {
    "parser": {
      "jsx": true
    },
    "transform": {
      "react": {
        "runtime": "automatic"
      }
    }
  }
}

Это влияет на все файлы директории, содержащие JSX-синтаксис, обеспечивая единообразную трансформацию компонентов.

Поведение при ошибках

При пакетной компиляции ошибки обрабатываются на уровне отдельных файлов:

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

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

Использование в автоматизированных сборках

Компиляция директории часто применяется в:

  • CI/CD пайплайнах
  • сборке npm-пакетов
  • серверной транспиляции
  • prepublish этапах

Типичный сценарий: 

swc src -d lib

с последующей публикацией содержимого lib.

Структурная консистентность результата

Одним из ключевых свойств пакетной компиляции является сохранение:

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

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

Оглавление