Интеграция в npm-скрипты

Интеграция SWC в npm-скрипты строится вокруг идеи замены традиционных транспиляторов (Babel, tsc в режиме трансформации) на высокопроизводительный компилятор, выполняющий преобразование JavaScript и TypeScript через нативные биндинги. SWC работает как CLI-инструмент и как программный API, но в контексте npm-скриптов чаще используется именно CLI-обёртка @swc/cli.

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

Установка зависимостей

Базовый набор пакетов для интеграции SWC в npm-скрипты включает CLI и ядро компилятора: 

npm install -D @swc/core @swc/cli

Для проектов с TypeScript дополнительно требуется типовая конфигурация через .swcrc, так как SWC не использует tsconfig.json как основной источник трансформационных правил (он используется лишь частично в связке с type-checker инструментами).

В ряде сценариев подключаются вспомогательные пакеты:

  • rimraf — очистка директорий перед сборкой
  • chokidar-cli или встроенный –watch режим SWC
  • cross-env — кроссплатформенные переменные окружения
  • npm-run-all или concurrently — параллельное выполнение задач

Базовые npm-скрипты сборки

Стандартная структура package.json при использовании SWC ориентирована на разделение режимов сборки и разработки.

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

{
  "scripts": {
    "build": "swc src -d dist"
  }
}

Команда выполняет трансформацию директории src в директорию dist, сохраняя структуру файлов и применяя настройки из .swcrc.

Режим разработки 

{
  "scripts": {
    "dev": "swc src -d dist --watch"
  }
}

Флаг –watch активирует отслеживание изменений файлов. SWC компилирует только изменённые модули, что снижает нагрузку по сравнению с полным пересбором.

Разделение входа и выхода

SWC поддерживает гибкое определение путей: 

{
  "scripts": {
    "build": "swc ./source -d ./build"
  }
}

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

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

Файл .swcrc является центральной точкой управления поведением SWC.

Базовая конфигурация для JavaScript и TypeScript 

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

Особенности конфигурации

  • jsc.parser.syntax определяет тип входного синтаксиса (ecmascript / typescript)
  • target управляет уровнем транспиляции
  • module.type задаёт формат модулей (commonjs, esm, umd)
  • sourceMaps обеспечивает отладку после компиляции

Интеграция TypeScript без tsc в пайплайне

SWC способен трансформировать TypeScript без проверки типов. Это влияет на архитектуру npm-скриптов: проверка типов отделяется от сборки.

Разделение сборки и type-check 

{
  "scripts": {
    "build": "npm run clean && swc src -d dist",
    "typecheck": "tsc --noEmit"
  }
}

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

Параллельное выполнение 

{
  "scripts": {
    "build": "npm-run-all clean typecheck compile",
    "compile": "swc src -d dist"
  }
}

Очистка и подготовка окружения

Перед сборкой часто требуется удаление старых артефактов: 

{
  "scripts": {
    "clean": "rimraf dist",
    "build": "npm run clean && swc src -d dist"
  }
}

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

Режим разработки с пересборкой

Для повышения эффективности разработки SWC интегрируется с файловыми наблюдателями: 

{
  "scripts": {
    "dev": "npm-run-all --parallel watch serve",
    "watch": "swc src -d dist --watch",
    "serve": "node dist/index.js"
  }
}

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

Интеграция с ESM и CommonJS

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

CommonJS 

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

ES Modules 

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

В npm-скриптах это позволяет создавать разные сборки: 

{
  "scripts": {
    "build:cjs": "swc src -d dist/cjs",
    "build:esm": "swc src -d dist/esm"
  }
}

Монорепозитории и раздельная сборка пакетов

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

{
  "scripts": {
    "build:pkg-a": "swc packages/pkg-a/src -d packages/pkg-a/dist",
    "build:pkg-b": "swc packages/pkg-b/src -d packages/pkg-b/dist"
  }
}

Для масштабирования применяется параллелизация: 

{
  "scripts": {
    "build": "npm-run-all --parallel build:*"
  }
}

Интеграция с тестовыми окружениями

SWC может использоваться как трансформер для тестовых раннеров.

Jest + SWC 

{
  "jest": {
    "transform": {
      "^.+\\.(t|j)sx?$": ["@swc/jest"]
    }
  }
}

npm-скрипты при этом остаются минимальными: 

{
  "scripts": {
    "test": "jest"
  }
}

SWC устраняет необходимость Babel-трансформации тестового кода, ускоряя запуск тестов.

Переменные окружения в npm-скриптах

SWC может учитывать окружение сборки: 

{
  "scripts": {
    "build:prod": "cross-env NODE_ENV=production swc src -d dist",
    "build:dev": "cross-env NODE_ENV=development swc src -d dist"
  }
}

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

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

SWC изначально ориентирован на высокую скорость, но интеграция в npm-скрипты позволяет дополнительно ускорить процесс:

  • исключение лишних шагов (Babel, лишние линтеры в build pipeline)
  • разделение type-check и compile
  • использование watch-режима вместо полного пересборa
  • параллелизация задач через npm-run-all

Дополнительная оптимизация достигается за счёт минимизации входных директорий: 

{
  "scripts": {
    "build": "swc src --ignore **/*.test.ts -d dist"
  }
}

Обработка ошибок и диагностика сборки

SWC выводит ошибки компиляции в stdout/stderr, что позволяет напрямую использовать npm-скрипты без дополнительных обработчиков.

Типовая структура диагностики:

  • синтаксические ошибки TypeScript
  • несовместимые конструкции ECMAScript
  • ошибки конфигурации .swcrc

Для повышения читаемости логов используется режим: 

{
  "scripts": {
    "build": "swc src -d dist --quiet"
  }
}

или наоборот подробный вывод при отладке: 

{
  "scripts": {
    "build:debug": "swc src -d dist --log-level debug"
  }
}

Инкрементальная архитектура npm-скриптов со SWC

При масштабировании проекта SWC интегрируется в многоуровневый пайплайн:

  • очистка артефактов
  • проверка типов (опционально)
  • трансформация SWC
  • постобработка (копирование assets, генерация деклараций)
  • запуск runtime

Пример структуры: 

{
  "scripts": {
    "clean": "rimraf dist",
    "typecheck": "tsc --noEmit",
    "compile": "swc src -d dist",
    "postbuild": "node scripts/copy-assets.js",
    "build": "npm-run-all clean typecheck compile postbuild"
  }
}

Такая композиция делает SWC центральным элементом сборки, вокруг которого выстраиваются вспомогательные процессы без потери производительности.

Оглавление