Подключение @swc/core в Node.js

Библиотека @swc/core представляет собой высокопроизводительный компилятор JavaScript и TypeScript, написанный на Rust и предоставляющий Node.js-интерфейс для трансформации кода. Основное назначение — замена Babel и частично TypeScript Compiler (tsc) в задачах транспиляции.

Перед подключением требуется наличие Node.js актуальной LTS-ветки, поскольку бинарные зависимости SWC распространяются под конкретные платформы и архитектуры.

Установка выполняется через npm: 

npm install @swc/core

При использовании Yarn: 

yarn add @swc/core

При установке автоматически подбираются нативные бинарные файлы под текущую платформу. В случае нестандартных окружений (Alpine Linux, ARM-сборки, CI-системы) может потребоваться дополнительная настройка зависимостей libc или установка соответствующего platform-specific пакета.

Базовая архитектура @swc/core в Node.js

Пакет @swc/core предоставляет низкоуровневое API для трансформации кода. Основные возможности:

  • компиляция TypeScript → JavaScript
  • трансформация современного ECMAScript в совместимый код
  • JSX-преобразования (React и аналоги)
  • минимизация (в связке с отдельными инструментами)
  • программный доступ к AST-трансформации через плагины SWC

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

Ключевые функции:

  • transformSync
  • transform
  • parseSync
  • parse
  • bundle (в некоторых конфигурациях)

Подключение модуля в Node.js

CommonJS 

const swc = require("@swc/core");

ESM 

import * as swc from "@swc/core";

В обоих случаях доступен полный API трансформации.

Простейшая трансформация кода

Синхронный вариант 

const swc = require("@swc/core");

const inputCode = `
  const sum = (a, b) => a + b;
  console.log(sum(2, 3));
`;

const output = swc.transformSync(inputCode, {
  jsc: {
    parser: {
      syntax: "ecmascript"
    },
    target: "es5"
  }
});

console.log(output.code);

Синхронный режим выполняется блокирующе и подходит для скриптов сборки, CLI-инструментов и одноразовой компиляции.

Асинхронный вариант 

const swc = require("@swc/core");

(async () => {
  const result = await swc.transform(`
    const multiply = (a, b) => a * b;
  `, {
    jsc: {
      parser: {
        syntax: "ecmascript"
      },
      target: "es2020"
    }
  });

  console.log(result.code);
})();

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

Конфигурация компиляции

Основная настройка осуществляется через объект конфигурации, где ключевым разделом является jsc.

Структура конфигурации 

{
  jsc: {
    parser: {
      syntax: "typescript" | "ecmascript" | "jsx",
      tsx: boolean,
      jsx: boolean
    },
    target: "es3" | "es5" | "es2015" | "es2020" | "es2022",
    transform: {
      react: {
        runtime: "automatic" | "classic"
      }
    }
  },
  module: {
    type: "commonjs" | "es6" | "esnext"
  }
}

Поддержка TypeScript

SWC обрабатывает TypeScript без выполнения type-checking. Это ключевое отличие от tsc. 

const swc = require("@swc/core");

const tsCode = `
  function add(a: number, b: number): number {
    return a + b;
  }
`;

const result = swc.transformSync(tsCode, {
  jsc: {
    parser: {
      syntax: "typescript",
      tsx: false
    },
    target: "es2020"
  }
});

console.log(result.code);

Особенности:

  • типы удаляются полностью
  • интерфейсы и enums транспилируются в JS-конструкции
  • отсутствует проверка типов во время выполнения трансформации

Обработка JSX и React

SWC имеет встроенную поддержку JSX без дополнительных плагинов. 

const input = `
  const App = () => <div>Hello</div>;
`;

const output = swc.transformSync(input, {
  jsc: {
    parser: {
      syntax: "jsx"
    },
    transform: {
      react: {
        runtime: "automatic",
        importSource: "react"
      }
    }
  }
});

Режим automatic позволяет исключить необходимость ручного импорта React в каждом файле.

Работа с модулями

CommonJS вывод 

swc.transformSync(code, {
  module: {
    type: "commonjs"
  }
});

ES Modules 

swc.transformSync(code, {
  module: {
    type: "es6"
  }
});

Полный контроль над импортами

SWC поддерживает преобразование импортов, включая:

  • dynamic import
  • named exports
  • interop между CJS и ESM

Использование SWC как трансформера в рантайме Node.js

Одним из распространённых сценариев является подключение SWC для выполнения TypeScript/modern JS без предварительной сборки.

Подход через require hook (устаревающий стиль, но встречается) 

require("@swc/core/register");

После подключения файлы .ts и .tsx могут выполняться напрямую через Node.js.

Программный AST-пайплайн

SWC предоставляет возможность работы с AST: 

const swc = require("@swc/core");

const ast = swc.parseSync("const x = 1;", {
  syntax: "ecmascript"
});

console.log(ast);

AST можно использовать для:

  • статического анализа
  • написания кастомных трансформаций
  • интеграции с инструментами линтинга

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

SWC проектировался как высокопроизводительная замена Babel, поэтому ключевые особенности:

  • нативная реализация на Rust
  • многопоточная обработка внутри ядра
  • минимальные накладные расходы Node.js API

Практические моменты:

  • предпочтение transformSync в build-скриптах
  • использование transform в серверных приложениях
  • кэширование результатов трансформации на уровне файловой системы
  • исключение повторной обработки одинаковых модулей

Обработка ошибок компиляции

Ошибки SWC возвращаются в виде исключений: 

try {
  swc.transformSync("const x: = 1", {
    jsc: {
      parser: {
        syntax: "typescript"
      }
    }
  });
} catch (err) {
  console.error(err);
}

Типичные категории ошибок:

  • синтаксические ошибки входного кода
  • несовместимость парсера и синтаксиса
  • ошибки конфигурации трансформации

Интеграция в Node.js-проекты

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

SWC часто выступает ядром:

  • сборщиков фронтенда
  • серверных бандлеров
  • CLI-инструментов
  • генераторов кода

Типовой pipeline:

  1. чтение файлов проекта
  2. трансформация через SWC
  3. запись результата
  4. дальнейшая сборка или выполнение

Пример мини-сборщика 

const fs = require("fs");
const swc = require("@swc/core");

const input = fs.readFileSync("./input.ts", "utf-8");

const output = swc.transformSync(input, {
  jsc: {
    parser: {
      syntax: "typescript"
    },
    target: "es2020"
  },
  module: {
    type: "commonjs"
  }
});

fs.writeFileSync("./output.js", output.code);

Особенности окружения Node.js

При использовании SWC в Node.js учитываются следующие факторы:

  • различия между ESM и CommonJS режимами выполнения
  • поддержка type: module в package.json
  • влияние версий Node.js на загрузку нативных биндингов
  • архитектура CPU (x64, arm64)

В контейнерных средах (Docker) важно соответствие libc (glibc vs musl), иначе возможны ошибки загрузки бинарных модулей.

Расширенные возможности конфигурации

SWC поддерживает дополнительные трансформации:

  • опциональные chaining (?.)
  • nullish coalescing (??)
  • decorators (экспериментально, зависит от конфигурации)
  • class fields

Пример: 

swc.transformSync(code, {
  jsc: {
    transform: {
      legacyDecorator: true,
      decoratorMetadata: true
    }
  }
});

Режимы использования в реальных проектах

SWC в Node.js обычно используется в трёх режимах:

  • Build-time трансформация — сборка перед деплоем
  • Runtime трансформация — выполнение кода на лету
  • Tooling слой — анализ и генерация AST

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

Оглавление