Зависимости

При сборке с помощью 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 будет включён в итоговый бандл.

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

Для файлов деклараций по умолчанию tsdown не включает никакие зависимости. Это позволяет сохранять .d.ts чистыми и сфокусированными только на типах вашей библиотеки.

Настройка разрешения типов

С помощью опции dts.resolve можно явно указать, типы каких зависимостей нужно включить в .d.ts:

tsdown.config.ts

import { defineConfig } from 'tsdown'

export default defineConfig({
  dts: {
    resolve: ['lodash', /^@types\//],
  },
})

В этом примере типы для lodash и всех пакетов с префиксом @types будут включены в итоговые декларации.

Опция Resolver

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

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

tsdown.config.ts

import { defineConfig } from 'tsdown'

export default defineConfig({
  dts: {
    resolve: ['@babel/generator'],
    resolver: 'tsc',
  },
})

Если вы хотите собрать все типы, можно установить resolve: true. Однако настоятельно рекомендуется также установить resolver: 'tsc', чтобы минимизировать неожиданные проблемы:

tsdown.config.ts

import { defineConfig } from 'tsdown'

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

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

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

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