Целевая платформа (Target)

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

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

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

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

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

По умолчанию tsdown считывает поле engines.node из вашего файла package.json и автоматически устанавливает параметр target на минимальную совместимую версию Node.js, указанную в этом поле. Это обеспечивает совместимость сгенерированного кода с окружениями, которые вы объявили для вашего пакета.

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

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

Тогда tsdown автоматически установит параметр target как 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

Вы можете указать целевую платформу с помощью опции --target:

tsdown --target <платформа>

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

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

Пример

tsdown --target es2020

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

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 под указанные версии браузеров. Например, вложенный селектор 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.