Исполняемый файл

Экспериментальная функция

Опция exe находится в стадии экспериментальной разработки и может измениться в будущих релизах.

tsdown позволяет упаковать ваш код на TypeScript/JavaScript в автономный исполняемый файл с помощью Single Executable Applications в Node.js. На выходе получается нативный бинарный файл, который запускается без необходимости установки Node.js.

Требования

• Node.js >= 25.5.0 (поддержка ESM требует версии >= 25.7.0)
• Не поддерживается в Bun и Deno

Базовое использование

tsdown src/cli.ts --exe

Или в конфигурационном файле:

tsdown.config.ts

export default defineConfig({
  entry: ['src/cli.ts'],
  exe: true,
})

При включённой опции exe:

• Формат вывода по умолчанию меняется с esm на cjs (за исключением Node.js >= 25.7.0, где поддерживается ESM)
• Генерация файлов объявлений (dts) отключается по умолчанию
• Разделение кода отключается
• Поддерживаются только единичные точки входа

Расширенная конфигурация

Для более тонкой настройки можно передать объект в опцию exe:

tsdown.config.ts

export default defineConfig({
  entry: ['src/cli.ts'],
  exe: {
    fileName: 'my-tool',
    seaConfig: {
      disableExperimentalSEAWarning: true,
      useCodeCache: true,
    },
  },
})

fileName

Пользовательское имя выходного файла исполняемого файла. Не указывайте расширения .exe, суффиксы платформы или архитектуры — они добавляются автоматически.

Может быть строкой или функцией:

tsdown.config.ts

export default defineConfig({
  entry: ['src/cli.ts'],
  // строка
  exe: { fileName: 'my-tool' },
  // или функция
  // exe: { fileName: (chunk) => `my-tool-${chunk.name}` },
})

seaConfig

Передаёт параметры непосредственно в Node.js. Полное описание см. в документации Node.js.

Опция	Тип	По умолчанию	Описание
disableExperimentalSEAWarning	boolean	true	Отключить предупреждение об экспериментальном статусе
useSnapshot	boolean	false	Использовать снапшот V8 для ускорения запуска
useCodeCache	boolean	false	Использовать кэш кода V8 для ускорения запуска
execArgv	string[]	—	Дополнительные аргументы командной строки Node.js
execArgvExtension	'none' | 'env' | 'cli'	'env'	Способ расширения execArgv во время выполнения
assets	Record<string, string>	—	Ресурсы для встраивания в исполняемый файл

Кроссплатформенная сборка

По умолчанию exe собирает исполняемый файл для текущей платформы. Чтобы собирать исполняемые файлы для нескольких платформ с одной машины, установите пакет @tsdown/exe и используйте опцию targets:

pnpm

pnpm add -D @tsdown/exe

npm

npm install -D @tsdown/exe

yarn

yarn add -D @tsdown/exe

tsdown.config.ts

export default defineConfig({
  entry: ['src/cli.ts'],
  exe: {
    targets: [
      { platform: 'linux', arch: 'x64', nodeVersion: '25.7.0' },
      { platform: 'darwin', arch: 'arm64', nodeVersion: '25.7.0' },
      { platform: 'win', arch: 'x64', nodeVersion: '25.7.0' },
    ],
  },
})

Эта конфигурация загружает бинарный файл Node.js для целевой платформы с nodejs.org, кэширует его локально и использует для сборки исполняемого файла. Выходные файлы получают суффиксы платформы и архитектуры:

dist/
  cli-linux-x64
  cli-darwin-arm64
  cli-win-x64.exe

Параметры целевой платформы

Каждый элемент массива targets принимает следующие параметры:

Поле	Тип	Описание
platform	'win' | 'darwin' | 'linux'	Целевая операционная система (в соответствии с именами на nodejs.org)
arch	'x64' | 'arm64'	Целевая архитектура процессора
nodeVersion	string	Версия Node.js для использования (должна быть >=25.7.0)

WARNING

При указании targets опция seaConfig.executable игнорируется — вместо неё используется загруженный бинарный файл Node.js.

Примечание

При генерации кроссплатформенных исполняемых файлов (например, сборка для linux-x64 на машине darwin-arm64) параметры useCodeCache и useSnapshot должны быть установлены в false, чтобы избежать создания несовместимых исполняемых файлов. Поскольку кэш кода и снапшоты могут загружаться только на той же платформе, на которой они были скомпилированы, исполняемый файл может аварийно завершиться при попытке загрузки кэша или снапшота, собранного на другой платформе.

Кэширование

Загруженные бинарные файлы Node.js кэшируются в системной директории кэша:

• macOS: ~/Library/Caches/tsdown/node/
• Linux: ~/.cache/tsdown/node/ (или $XDG_CACHE_HOME/tsdown/node/)
• Windows: %LOCALAPPDATA%/tsdown/Caches/node/

Последующие сборки повторно используют кэшированные бинарные файлы без повторной загрузки.

Особенности платформ

• В macOS исполняемый файл автоматически подписывается кодом (в режиме ad-hoc) для совместимости с Gatekeeper. При кросс-компиляции для macOS с немacOS-хоста подпись кода пропускается с предупреждением.
• В Windows расширение .exe добавляется автоматически.