Прослойки (Shims)

Прослойки — это небольшие фрагменты кода, обеспечивающие совместимость между различными системами модулей, такими как CommonJS (CJS) и ECMAScript Modules (ESM). В tsdown прослойки используются для обеспечения совместимости между этими системами, гарантируя, что ваш код будет работать корректно в различных средах.

Переменные CommonJS в ESM

В CommonJS __dirname и __filename являются встроенными переменными, которые предоставляют путь к директории и файлу текущего модуля. Однако, эти переменные недоступны в ESM по умолчанию.

Для улучшения совместимости, когда опция shims включена, tsdown автоматически генерирует эти переменные для вывода в формате ESM. Например:

console.log(__dirname) // Доступно в ESM при включенных прослойках
console.log(__filename) // Доступно в ESM при включенных прослойках

Влияние на производительность

Сгенерированные прослойки для __dirname и __filename создают минимальное дополнительное потребление ресурсов во время выполнения. Однако, если эти переменные не используются в вашем коде, они будут автоматически удалены в процессе сборки, гарантируя, что ненужный код не будет включен.

Функция require в ESM

При использовании функции require в выходном формате ESM, когда параметр platform установлен в node, tsdown автоматически внедряет прослойку для require, используя createRequire из Node.js, независимо от настройки shims. Это позволяет использовать require в ESM-модулях в среде Node.js без дополнительной настройки.

Например:

// const require = createRequire(import.meta.url) [автоматически добавлено]

const someModule = require('some-module')

Эта функция всегда активна для ESM-вывода, предназначенного для Node.js, поэтому вам не нужно ничего дополнительно настраивать для использования require в таком сценарии.

Переменные ESM в CommonJS

Даже если опция shims не включена, tsdown автоматически добавит прослойки для следующих переменных, специфичных для ESM, в вывод CommonJS:

• import.meta.url
• import.meta.dirname
• import.meta.filename

Эти переменные предоставляются для обеспечения совместимости при использовании функций в стиле ESM в среде CommonJS. Например:

console.log(import.meta.url)
console.log(import.meta.dirname)
console.log(import.meta.filename)

Это поведение всегда включено для вывода в формате CommonJS, поэтому вам не нужно ничего настраивать для использования этих переменных.

Включение прослоек

Чтобы включить прослойки для __dirname и __filename в выводе ESM, используйте опцию --shims в CLI или установите shims: true в конфигурационном файле:

CLI

tsdown --shims

Конфигурационный файл

tsdown.config.ts

import { defineConfig } from 'tsdown'

export default defineConfig({
  shims: true,
})