Зависимости

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

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

dependencies и peerDependencies

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

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

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

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

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

Пропуск сборки модулей из Node Modules

Если нужно пропустить обработку и сборку всех зависимостей из node_modules, включите опцию skipNodeModulesBundle в конфигурации:

import { defineConfig } from 'tsdown'

export default defineConfig({
  skipNodeModulesBundle: true,
})

Это не позволит tsdown обрабатывать и собирать какие-либо зависимости из node_modules, независимо от того, как они используются в коде.

Настройка обработки зависимостей

tsdown предоставляет две опции для изменения поведения по умолчанию:

Опция external

Опция external позволяет явно указать, какие зависимости должны считаться внешними и не попадать в бандл:

tsdown.config.ts

import { defineConfig } from 'tsdown'

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

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

Опция noExternal

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

tsdown.config.ts

import { defineConfig } from 'tsdown'

export default defineConfig({
  noExternal: ['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',
  },
})

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

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

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