Поле env.mode и corejs
В экосистеме SWC поле `env` в конфигурации играет ключевую роль при транспиляции современного JavaScript в совместимый код для целевых окружений. Оно управляет тем, как и когда подключаются полифилы, какие трансформации применяются к синтаксису и каким образом учитываются возможности целевых рантаймов. Внутри `env` особое значение имеют параметры `mode` и `coreJs`, определяющие стратегию работы с полифилами и совместимостью.
## Структура env в SWC
Объект `env` обычно используется внутри `.swcrc` или программной конфигурации:
```json
{
"jsc": {
"target": "es5"
},
"env": {
"mode": "usage",
"coreJs": "3.33"
}
}
```
Основная задача `env` — управление автоматической полифилизацией на основе анализа кода и целевых платформ.
---
## Поле env.mode
`mode` определяет стратегию вставки полифилов из core-js и поведение анализа использования современных API.
### Основные режимы
### usage
Режим `usage` включает автоматическую вставку полифилов только для тех возможностей, которые реально используются в коде.
Принцип работы:
* анализируются конкретные выражения в исходном коде;
* определяется, какие встроенные функции или объекты отсутствуют в целевых окружениях;
* добавляются только необходимые импорты из core-js.
Пример:
```js
const set = new Set([1, 2, 3]);
```
При `mode: "usage"` SWC может добавить:
```js
import "core-js/modules/es.set";
```
Особенности:
* минимальный размер бандла;
* точечная полифилизация;
* требует точной настройки targets;
* увеличивает время компиляции из-за анализа AST.
---
### entry
Режим `entry` предполагает, что полифилы подключаются на основе явной точки входа приложения.
Принцип работы:
* разработчик вручную импортирует core-js в entry-файле;
* SWC переписывает импорт в набор необходимых модулей в зависимости от targets;
* анализ использования кода не выполняется на уровне отдельных выражений.
Пример входного кода:
```js
import "core-js";
```
После обработки:
```js
import "core-js/modules/es.array.for-each";
import "core-js/modules/es.object.keys";
import "core-js/modules/es.promise";
```
Особенности:
* более предсказуемое поведение;
* проще отлаживать;
* может включать лишние полифилы;
* меньше нагрузка на анализ кода.
---
### Сравнение usage и entry
| Характеристика | usage | entry |
| --------------------- | -------------- | ------------------- |
| Уровень анализа | выражения | точка входа |
| Размер бандла | минимальный | потенциально больше |
| Скорость сборки | ниже | выше |
| Управляемость | автоматическая | ручная |
| Риск лишних полифилов | низкий | средний |
---
## Поле env.coreJs
`coreJs` определяет версию библиотеки core-js, используемой для полифилов.
### Назначение
Значение этого поля необходимо для:
* выбора корректных путей импорта модулей;
* обеспечения совместимости с API конкретной версии core-js;
* предотвращения конфликтов между различными версиями полифилов.
### Пример конфигурации
```json
{
"env": {
"mode": "usage",
"coreJs": "3.30"
}
}
```
---
## Влияние версии core-js
Разные версии core-js имеют различную структуру модулей.
### core-js v2 (устаревшая модель)
* глобальные полифилы;
* менее гранулярная структура;
* часто конфликтует с современными сборщиками.
SWC ориентирован на core-js v3, поэтому v2 практически не используется.
---
### core-js v3
Основная актуальная версия:
* модульная архитектура (`core-js/modules/...`);
* поддержка точечной загрузки;
* совместимость с `usage` режимом;
* оптимизация под tree-shaking.
Пример генерируемого импорта:
```js
import "core-js/modules/es.promise";
import "core-js/modules/es.array.includes";
```
---
## Взаимодействие env.mode и coreJs
`mode` и `coreJs` тесно связаны, поскольку определяют механизм генерации полифилов.
### usage + coreJs
При такой комбинации:
* SWC анализирует AST;
* определяет недостающие API;
* сопоставляет их с модульной структурой core-js версии, указанной в `coreJs`;
* вставляет точечные импорты.
Пример:
```json
{
"env": {
"mode": "usage",
"coreJs": "3.25"
}
}
```
Результат:
* импортируются только модули, присутствующие в core-js 3.25;
* исключаются API, отсутствующие в указанной версии.
---
### entry + coreJs
В этом режиме:
* разработчик импортирует core-js вручную;
* SWC использует `coreJs` для определения набора модулей;
* трансформация затрагивает только точку входа.
Особенность:
* версия core-js влияет на список доступных модулей, но не на анализ кода.
---
## Поведение при отсутствии env.mode
Если `mode` не задан:
* автоматическая полифилизация может быть отключена;
* поведение зависит от версии SWC и preset-env;
* часто требуется явное указание стратегии для предсказуемости сборки.
---
## Типовые конфигурации
### Минимальная сборка для современных браузеров
```json
{
"jsc": {
"target": "es2020"
},
"env": {
"mode": "usage",
"coreJs": "3.30"
}
}
```
---
### Совместимость со старыми окружениями
```json
{
"jsc": {
"target": "es5"
},
"env": {
"mode": "entry",
"coreJs": "3.30"
}
}
```
---
## Практическое влияние на сборку
Комбинация `env.mode` и `coreJs` напрямую влияет на:
* размер итогового бандла;
* количество импортируемых полифилов;
* скорость сборки;
* предсказуемость поведения в разных окружениях;
* совместимость с legacy-браузерами.
В сложных проектах выбор между `usage` и `entry` становится архитектурным решением, определяющим стратегию доставки JavaScript-кода в разные среды исполнения.