Окружение сборки (target)

Опция target задаёт, под какое окружение сборки понижать синтаксис JavaScript и CSS (преобразовывать в более старый) и что оставить без изменений. Так можно контролировать совместимость кода с нужными версиями JavaScript или средами.

Например, логическое присваивание a ||= b будет преобразовано в a || (a = b), если окружение сборки — es2015.

Поддерживается только преобразование современного синтаксиса в более старый (syntax downgrade)

Опция target влияет только на синтаксис. Она не добавляет полифиллы и не подключает API, которых может не быть в окружении выполнения. Например, для Promise поддержка не подставится сама — полифиллы нужно подключать отдельно.

Поведение опции target по умолчанию

По умолчанию tsdown берёт поле engines.node из package.json и выставляет окружение сборки по минимальной указанной версии Node.js. Так собранный код остаётся совместимым с заявленными для пакета средами.

Например, если ваш package.json содержит:

{
  "engines": {
    "node": ">=18.0.0"
  }
}

Тогда окружение сборки будет установлено в node18.0.0.

Чтобы задать своё значение, укажите target в CLI или в конфиге.

Режим без преобразований

Чтобы отключить преобразования синтаксиса, установите target: false. Это позволит сохранить современный код JavaScript и CSS в исходном виде, игнорируя требования среды выполнения из package.json.

{
  "target": false
}

Что происходит при target: false:

• Современный JavaScript остается без изменений (optional chaining ?., nullish coalescing ?? и прочие новые возможности)
• CSS код не адаптируется под старые браузеры (включая современные возможности вроде нативной вложенности)
• Дополнительные полифиллы и хелперы не подключаются
• Финальный код идентичен исходному

Когда это нужно:

• Разработка для современных браузеров и сред выполнения
• Преобразования выполняются на других этапах сборки
• Создание библиотек, которые будут обрабатываться в финальном приложении

Поведение по умолчанию

Если не задать target и в package.json нет секции engines.node, tsdown автоматически работает в режиме target: false, оставляя весь код без преобразований.

Настройка окружения сборки

Окружение сборки задаётся опцией --target:

tsdown --target <окружение>

Поддерживаемые значения

• Версии ECMAScript: es2015, es2020, esnext и др.
• Браузеры: chrome100, safari18, firefox110 и др.
• Node.js: node20.18, node16 и др.

Пример

tsdown --target es2020

Можно указать несколько режимов сборки (несколько раз --target), чтобы обеспечить совместимость с разными средами.

tsdown --target chrome100 --target node20.18

Поддержка декораторов

В экосистеме JavaScript на данный момент существуют две основные реализации декораторов:

• Декораторы Stage 2 (устаревшие) — старая экспериментальная версия, часто называемая «legacy-декораторами».
• Декораторы Stage 3 — последняя официальная спецификация, значительно отличающаяся от предыдущей.

Если вы используете устаревшие декораторы Stage 2, включите опцию experimentalDecorators в файле tsconfig.json:

{
  "compilerOptions": {
    "experimentalDecorators": true
  }
}

Если вам нужны современные декораторы Stage 3 по спецификации TC39, обратите внимание, что tsdown (и его базовые движки Rolldown/Oxc) пока не поддерживают эту возможность. Актуальную информацию о поддержке декораторов Stage 3 можно найти в этой задаче на GitHub.

Примечание:
Эти две реализации декораторов существенно различаются. Убедитесь, что вы используете правильную конфигурацию и синтаксис для выбранной версии.

Адаптация CSS

tsdown может адаптировать CSS под выбранное окружение сборки (версии браузеров). Например, вложенный селектор с & будет развёрнут в плоскую структуру, если в окружении указан chrome108 или старше.

Чтобы включить адаптацию CSS, вам нужно вручную установить unplugin-lightningcss:

npm

npm install -D unplugin-lightningcss

pnpm

pnpm add -D unplugin-lightningcss

yarn

yarn add -D unplugin-lightningcss

bun

bun add -D unplugin-lightningcss

После установки укажите браузер в окружении сборки (например, target: 'chrome100') в конфиге или в CLI — адаптация CSS включится автоматически.

Для получения дополнительной информации о поддержке браузеров и совместимости CSS обратитесь к документации Lightning CSS.