Зависимости

При сборке с помощью tsdown зависимости обрабатываются автоматически, чтобы ваша библиотека оставалась лёгкой и удобной для использования. В этом разделе описано, как tsdown работает с разными типами зависимостей и как вы можете настроить это поведение под свои задачи.

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

dependencies, peerDependencies и optionalDependencies

По умолчанию tsdown не включает в бандл зависимости, указанные в полях dependencies, peerDependencies и optionalDependencies вашего package.json:

• dependencies: считаются внешними и не попадают в итоговый бандл. Они будут установлены автоматически при установке вашей библиотеки через npm или другой менеджер пакетов.
• peerDependencies: также считаются внешними. Пользователь вашей библиотеки должен установить их самостоятельно (иногда это делает менеджер пакетов автоматически).
• optionalDependencies: также считаются внешними. Они могут быть установлены или пропущены в зависимости от платформы пользователя и его конфигурации.

devDependencies и фантомные зависимости

• devDependencies: Пакеты из раздела devDependencies в package.json включаются в сборку только при фактическом импорте или использовании в исходном коде.
• Фантомные зависимости: Пакеты, находящиеся в node_modules, но не указанные в package.json, включаются в сборку только при их использовании в коде.

Другими словами, в сборку попадут только те devDependencies и фантомные зависимости, которые действительно используются в вашем проекте.

Опции deps

Все опции, относящиеся к обработке зависимостей, настраиваются внутри поля deps:

tsdown.config.ts

import { defineConfig } from 'tsdown'

export default defineConfig({
  deps: {
    neverBundle: ['lodash', /^@my-scope\//],
    alwaysBundle: ['some-package'],
    onlyBundle: ['cac', 'bumpp'],
    skipNodeModulesBundle: true,
  },
})

deps.skipNodeModulesBundle

Если вы хотите, чтобы зависимости из node_modules не попадали в бандл, включите skipNodeModulesBundle:

tsdown.config.ts

import { defineConfig } from 'tsdown'

export default defineConfig({
  deps: {
    skipNodeModulesBundle: true,
  },
})

При этой опции tsdown не включает в бандл зависимости из node_modules, независимо от того, как они используются в коде.

WARNING

skipNodeModulesBundle нельзя использовать вместе с alwaysBundle: эти опции взаимоисключающие.

deps.onlyBundle

Опция onlyBundle работает как список разрешённых зависимостей, которые можно включать в бандл из node_modules. Если в бандле окажется зависимость, которой нет в этом списке, tsdown завершит сборку с ошибкой. Это помогает не допустить, чтобы в больших проектах зависимости из node_modules случайно «затянулись» внутрь бандла.

tsdown.config.ts

import { defineConfig } from 'tsdown'

export default defineConfig({
  deps: {
    onlyBundle: ['cac', 'bumpp'],
  },
})

В этом примере в бандл могут попадать только cac и bumpp. Если будет импортирована любая другая зависимость из node_modules, tsdown завершит сборку с ошибкой и укажет, какой пакет был неожиданно включён и из каких файлов он импортировался.

Поведение

• onlyBundle — массив (например, ['cac', /^my-/]): в бандл могут попадать только зависимости, подходящие под список. Для остальных будет выброшена ошибка. Неиспользуемые шаблоны из списка также будут отражены в отчёте.
• onlyBundle — false: все проверки и предупреждения, связанные с включёнными в бандл зависимостями, отключаются.
• onlyBundle не задано (по умолчанию): если какая‑то зависимость из node_modules попадает в бандл, выводится предупреждение с рекомендацией добавить опцию onlyBundle или установить её в false, чтобы отключить предупреждения.

TIP

Указывайте в списке onlyBundle и все необходимые подзависимости, а не только пакеты верхнего уровня, которые вы импортируете напрямую.

deps.neverBundle

Опция neverBundle позволяет явно пометить отдельные зависимости как внешние, чтобы они не попадали в бандл вашей библиотеки. Например:

tsdown.config.ts

import { defineConfig } from 'tsdown'

export default defineConfig({
  deps: {
    neverBundle: ['lodash', /^@my-scope\//],
  },
})

В этом примере lodash и все пакеты с префиксом @my-scope будут считаться внешними.

Опция deps.alwaysBundle

Опция alwaysBundle позволяет принудительно включить в бандл отдельные зависимости, даже если они указаны в dependencies, peerDependencies или optionalDependencies. Например:

tsdown.config.ts

import { defineConfig } from 'tsdown'

export default defineConfig({
  deps: {
    alwaysBundle: ['some-package'],
  },
})

В этом случае some-package будет включён в итоговый бандл.

Работа с зависимостями в файлах деклараций

Логика сборки файлов деклараций соответствует правилам для JavaScript: зависимости упаковываются или помечаются как внешние по тем же правилам и опциям.

Опция Resolver

При сборке сложных типов сторонних библиотек могут возникать ситуации, когда стандартный резолвер (Oxc) не справляется с некоторыми сценариями. Например, типы для @babel/generator находятся в пакете @types/babel__generator, который может быть некорректно обработан Oxc.

Чтобы решить эту проблему, можно установить опцию resolver в значение tsc в вашей конфигурации. Это задействует нативный резолвер TypeScript, который работает медленнее, но гораздо лучше совместим со сложными настройками типов:

tsdown.config.ts

import { defineConfig } from 'tsdown'

export default defineConfig({
  dts: {
    resolver: 'tsc',
  },
})

Переход с устаревших опций

Перечисленные ниже опции верхнего уровня устарели. Перенесите настройки в объект deps:

Устаревшая опция	Новая опция
external	deps.neverBundle
noExternal	deps.alwaysBundle
inlineOnly	deps.onlyBundle
deps.onlyAllowBundle	deps.onlyBundle
skipNodeModulesBundle	deps.skipNodeModulesBundle

Краткое резюме

• По умолчанию:
  • dependencies, peerDependencies и optionalDependencies считаются внешними и не включаются в бандл.
  • devDependencies и фантомные зависимости включаются в сборку только если они фактически используются в вашем коде.
• Настройка:
  • Используйте deps.onlyBundle, чтобы разрешить включение в бандл только перечисленных зависимостей и завершать сборку с ошибкой при любых других.
  • Используйте deps.neverBundle, чтобы явно пометить отдельные зависимости как внешние.
  • Используйте deps.alwaysBundle, чтобы принудительно включить отдельные зависимости в бандл.
  • Используйте deps.skipNodeModulesBundle, чтобы зависимости из node_modules не попадали в бандл.
• Файлы деклараций:
  • Логика сборки файлов деклараций теперь аналогична JavaScript.
  • Используйте resolver: 'tsc' для лучшей совместимости со сложными типами сторонних библиотек.

Понимание и правильная настройка обработки зависимостей поможет сделать вашу библиотеку оптимальной по размеру и удобной для использования.