Import attributes
SWC поддерживает работу с import attributes (ранее известными как import assertions) как часть обработки современных модулей ECMAScript. Эта функциональность относится к механизму явного указания метаданных импортируемого ресурса и используется для строгой типизации и безопасной загрузки не-JavaScript модулей, таких как JSON, CSS, WebAssembly и других ресурсов, обрабатываемых через ESM-интерфейс.
Import attributes стали развитием идеи import assertions: вместо простого утверждения о типе ресурса теперь используется более гибкая система атрибутов, расширяемая в будущем. В контексте SWC эта возможность важна прежде всего для трансформации современного синтаксиса в совместимый JavaScript для сред выполнения, где поддержка import attributes может быть ограниченной или частичной.
## Синтаксис import attributes в ECMAScript
Базовая форма статического импорта с атрибутами выглядит следующим образом:
```javascript
import config from "./config.json" with { type: "json" };
```
Ключевой элемент конструкции — блок `with { ... }`, содержащий пары ключ-значение. Чаще всего используется атрибут `type`, который определяет тип загружаемого ресурса.
Расширенные варианты:
```javascript
import styles from "./styles.css" with { type: "css" };
import data from "./data.json" with { type: "json" };
import wasmModule from "./module.wasm" with { type: "wasm" };
```
Также поддерживается динамический импорт:
```javascript
const config = await import("./config.json", {
with: { type: "json" }
});
```
## Семантика import attributes
Import attributes не влияют на процесс резолва пути модуля. Их задача — передать метаданные рантайму загрузки:
* определение формата ресурса;
* выбор правильного загрузчика;
* предотвращение некорректной интерпретации (например, JSON как JS);
* подготовка к безопасной обработке нестандартных модулей.
Ключевой принцип: атрибуты являются частью контрактного описания импорта, а не механизмом трансформации данных.
## Поддержка import attributes в SWC
В SWC обработка import attributes реализуется на уровне парсера ECMAScript и трансформеров модулей. Основная задача — корректно:
* распарсить синтаксис `with { ... }`;
* сохранить или преобразовать его в зависимости от целевой среды;
* обеспечить совместимость с бандлерами и рантаймами.
В зависимости от конфигурации SWC может:
1. Оставлять import attributes без изменений (для современных сред).
2. Удалять атрибуты (если целевая среда их не поддерживает).
3. Трансформировать импорт в альтернативные формы (например, через runtime helpers или загрузчики).
## Конфигурация парсера SWC
Для поддержки import attributes в SWC важно включение соответствующих возможностей синтаксиса:
```json
{
"jsc": {
"parser": {
"syntax": "ecmascript",
"dynamicImport": true
}
}
}
```
В актуальных версиях SWC поддержка import assertions/attributes обычно включена по умолчанию, но поведение может зависеть от версии ECMAScript target.
## Трансформация import attributes
SWC может трансформировать код в зависимости от целевой платформы.
### Сценарий 1: сохранение синтаксиса
Если target поддерживает import attributes:
```javascript
import data from "./data.json" with { type: "json" };
```
остается без изменений.
### Сценарий 2: удаление attributes
При несовместимом target:
```javascript
import data from "./data.json";
```
При этом теряется информация о типе ресурса, что может потребовать дополнительной обработки на уровне бандлера.
### Сценарий 3: преобразование через runtime
В некоторых пайплайнах SWC совместно с бандлерами может трансформировать импорт:
```javascript
const data = __load_json("./data.json");
```
или аналогичные helper-функции, зависящие от окружения.
## Взаимодействие с бандлерами
Import attributes особенно важны в связке SWC с современными бандлерами (например, webpack, Vite, Rspack). В таких системах SWC выполняет роль быстрого транслятора синтаксиса, а семантическая интерпретация происходит уже на уровне сборщика.
Основные модели поведения:
* **Pass-through mode** — SWC сохраняет атрибуты, бандлер их интерпретирует.
* **Strip mode** — SWC удаляет атрибуты, оставляя только путь.
* **Transform mode** — SWC адаптирует импорт под внутренние плагины сборщика.
## import attributes и JSON модули
Наиболее распространённый сценарий — импорт JSON:
```javascript
import pkg from "./package.json" with { type: "json" };
```
Без атрибутов такой импорт может быть интерпретирован как обычный ESM, что приводит к ошибке выполнения. SWC помогает гарантировать, что синтаксис корректно проходит стадию трансформации.
При транспиляции для Node.js старых версий возможны альтернативные формы:
```javascript
const pkg = require("./package.json");
```
или динамическая загрузка через JSON loader.
## CSS и нестандартные модули
Import attributes также используются для не-JS ресурсов:
```javascript
import styles from "./app.css" with { type: "css" };
```
В экосистемах с поддержкой CSS Modules или constructable stylesheets SWC может сохранять или преобразовывать такие импорты в зависимости от конфигурации:
```javascript
const sheet = new CSSStyleSheet();
sheet.replaceSync(".class { color: red; }");
```
## WebAssembly и import attributes
Для WebAssembly модулей:
```javascript
import init from "./module.wasm" with { type: "wasm" };
```
SWC в данном случае обычно не интерпретирует бинарное содержимое, но обеспечивает корректную передачу метаданных дальше по пайплайну сборки.
## Ограничения и несовместимости
При работе с import attributes в SWC важно учитывать несколько ограничений:
* не все рантаймы поддерживают синтаксис `with {}`;
* некоторые версии Node.js требуют включения экспериментальных флагов;
* старые бандлеры могут полностью игнорировать атрибуты;
* трансформация SWC может привести к потере метаданных при неправильной конфигурации target.
Особенно критично различие между:
```javascript
import x from "./file.json" assert { type: "json" };
```
и
```javascript
import x from "./file.json" with { type: "json" };
```
Первый вариант относится к устаревшим import assertions, второй — к современным import attributes. SWC в зависимости от версии может поддерживать оба синтаксиса, но трансформации будут различаться.
## SWC и эволюция модульной системы
В контексте модульной системы ECMAScript import attributes являются частью более широкой эволюции:
* разделение кода и ресурсов;
* формализация типов импортируемых модулей;
* интеграция браузерного и серверного поведения ESM;
* унификация загрузчиков ресурсов.
SWC в этой архитектуре выступает как слой высокопроизводительной синтаксической обработки, обеспечивающий прохождение новых стандартов ECMAScript в существующих экосистемах без необходимости немедленного обновления рантаймов.
## Особенности отладки import attributes в SWC
При диагностике проблем в трансформации import attributes анализируются следующие аспекты:
* корректность парсинга `with`-блока;
* соответствие target ECMAScript версии;
* наличие конфликтов с бандлером;
* потеря атрибутов на этапе minification;
* взаимодействие с TypeScript-синтаксисом.
Типичный источник ошибок — несовпадение ожиданий рантайма и поведения SWC-трансформера, когда атрибуты удаляются, но код всё ещё рассчитывает на их интерпретацию.
## Влияние TypeScript и типизации
В TypeScript импорт с attributes не влияет на типовую систему напрямую, но может требовать деклараций для модулей:
```typescript
declare module "*.json" {
const value: any;
export default value;
}
```
SWC, работая как транспайлер TypeScript, не выполняет глубокую семантическую проверку import attributes, ограничиваясь синтаксическим преобразованием.
## Итоговая модель поведения в SWC-пайплайне
Поведение import attributes в SWC можно свести к трём уровням:
1. **Парсинг** — распознавание синтаксиса `with`.
2. **Трансформация** — адаптация под target environment.
3. **Передача** — сохранение метаданных для бандлера или рантайма.
Эта трёхуровневая модель позволяет интегрировать современный ECMAScript-синтаксис в разнородные среды исполнения без потери совместимости между браузером, Node.js и сборочными системами.