Компиляция одного файла

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

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

Основной конвейер включает несколько этапов:

  • парсинг исходного кода в AST (Abstract Syntax Tree)
  • применение трансформаций к дереву
  • генерация итогового JavaScript-кода
  • опциональная генерация source map

Каждый этап строго изолирован, что позволяет SWC достигать высокой скорости обработки даже при больших файлах.

CLI-компиляция одного файла

Наиболее прямой способ обработки одиночного файла — использование CLI-интерфейса SWC. Он предоставляет минимальный набор параметров для трансформации без необходимости подключения сборщиков.

Простейший запуск: 

swc input.js -o output.js

При такой конфигурации SWC:

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

Явное указание языка входа

Если требуется строгая интерпретация как TypeScript: 

swc input.ts -o output.js

SWC автоматически удаляет типы и выполняет трансформацию синтаксиса в JavaScript.

Включение source map

Для отладки одиночного файла часто используется генерация карт исходного кода: 

swc input.ts -o output.js --source-maps

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

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

При одиночной компиляции важную роль играет файл конфигурации .swcrc. Он определяет поведение трансформации независимо от CLI-параметров.

Пример базовой конфигурации: 

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

Парсер и синтаксис

Поле parser.syntax определяет, как SWC интерпретирует файл:

  • ecmascript — стандартный JavaScript
  • typescript — TypeScript с удалением типов
  • jsx — JSX-синтаксис (React и совместимые среды)

Выбор парсера влияет на структуру AST, а значит и на все последующие трансформации.

Target-уровень генерации

Параметр target определяет уровень JavaScript, который будет получен на выходе:

  • es3 / es5 — для устаревших окружений
  • es2015–es2022 — современные браузеры и Node.js
  • es2020+ — минимальная трансформация

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

Компиляция через @swc/core

Для программной обработки одного файла используется пакет @swc/core. Он предоставляет API, позволяющий встроить компиляцию в Node.js-окружение.

Базовый пример трансформации 

import { transformFile } from "@swc/core";

const result = await transformFile("input.ts", {
  jsc: {
    parser: {
      syntax: "typescript"
    },
    target: "es2020"
  },
  module: {
    type: "commonjs"
  }
});

console.log(result.code);

Функция transformFile выполняет полный цикл обработки:

  • чтение файла
  • парсинг
  • трансформация AST
  • генерация кода

Использование transform вместо transformFile

Если исходный код уже загружен в память: 

import { transform } from "@swc/core";

const sourceCode = `
  const value: number = 42;
  console.log(value);
`;

const result = await transform(sourceCode, {
  filename: "example.ts",
  jsc: {
    parser: {
      syntax: "typescript"
    },
    target: "es2020"
  }
});

Здесь SWC не выполняет файловый ввод-вывод и работает только с переданной строкой.

Обработка TypeScript в одном файле

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

Пример входного кода: 

function sum(a: number, b: number): number {
  return a + b;
}

После компиляции: 

function sum(a, b) {
  return a + b;
}

Ограничения одиночной компиляции TS

При работе с одним файлом важно учитывать:

  • отсутствует type-checking
  • нет анализа зависимостей типов между файлами
  • декораторы обрабатываются только синтаксически
  • namespace и advanced TS features могут требовать дополнительных опций

JSX-трансформация

SWC поддерживает JSX как часть одиночной компиляции без необходимости подключения Babel.

Пример: 

const element = <div className="box">Text</div>;

Результат зависит от настроек runtime:

React 17+ (automatic runtime) 

import { jsx as _jsx } from "react/jsx-runtime";

const element = _jsx("div", {
  className: "box",
  children: "Text"
});

Classic runtime 

const element = React.createElement("div", {
  className: "box"
}, "Text");

Выбор режима определяется параметром: 

{
  "jsc": {
    "transform": {
      "react": {
        "runtime": "automatic"
      }
    }
  }
}

Минификация одиночного файла

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

CLI-вариант: 

swc input.js -o output.min.js -C minify=true

Основные преобразования:

  • удаление пробелов и комментариев
  • сокращение имен переменных
  • упрощение выражений
  • inline-константы

Программный вариант: 

import { minify } from "@swc/core";

const result = await minify("const a = 1 + 2;", {
  compress: true,
  mangle: true
});

Source map при одиночной трансформации

Source map играет критическую роль при отладке: 

{
  "sourceMaps": true,
  "inlineSourcesContent": true
}

SWC формирует mapping между:

  • исходными строками
  • трансформированным кодом
  • позициями AST-узлов

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

Особенности генерации AST в одиночном файле

В режиме single-file SWC оптимизирует структуру AST:

  • отсутствует объединение модулей
  • scope ограничен текущим файлом
  • импорты и экспорты не резолвятся, а лишь трансформируются
  • tree-shaking не выполняется

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

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

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

  1. чтение файла или строки
  2. выбор парсера (JS/TS/JSX)
  3. построение AST
  4. применение трансформаций (preset-env, react, decorators)
  5. генерация кода
  6. формирование source map (если включено)

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

Трансформации и плагины в одном файле

SWC поддерживает плагины, которые могут быть подключены даже при одиночной обработке.

Пример концептуальной конфигурации: 

{
  "jsc": {
    "experimental": {
      "plugins": [
        ["plugin-name", { "option": true }]
      ]
    }
  }
}

Плагины работают на уровне AST и могут:

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

Работа с модулями в одиночном файле

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

  • import → CommonJS или ESM в зависимости от конфигурации
  • export → совместимый формат целевого окружения

Пример трансформации: 

export const a = 1;

в CommonJS: 

exports.a = 1;

или в ESM (если не требуется трансформация): 

export const a = 1;

Влияние target и module type на результат

Комбинация параметров:

  • jsc.target
  • module.type

определяет итоговую форму файла.

Типовые комбинации:

  • ES2020 + ES modules → минимальная трансформация
  • ES5 + CommonJS → максимальная совместимость
  • ES2022 + ESM → современный нативный код

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

Оглавление