📦 TypeScript Bundler (tsb)

CLI инструмент для объединения JavaScript и TypeScript definition файлов в единые бандлы.

🚀 Быстрый старт

Установка

# Установка из npm
npm install -g @hren/typescript-bundler

# Или установка из репозитория
git clone https://github.com/MagIlyasDOMA/typescript-bundler.git
cd typescript-bundler
npm install
npm run build
npm link

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

# Объединить все .js и .d.ts файлы из директории src
tsb ./src --js-file ./dist/bundle.js --dts-file ./dist/bundle.d.ts

# Только JavaScript файлы
tsb ./src --js-file ./dist/bundle.js

# Только TypeScript definition файлы
tsb ./src --dts-file ./dist/bundle.d.ts

📖 Документация

Синтаксис команды

tsb <input-dir> [опции]

Обязательные параметры

• <input-dir> - путь к директории с исходными файлами

Опции

| Опция | Алиас | Описание | Пример | |-------|-------|----------|--------| | --js-file | -j | Путь к выходному JS файлу | -j ./dist/bundle.js | | --dts-file | -d | Путь к выходному DTS файлу | -d ./dist/bundle.d.ts | | --exclude | -e | Паттерны для исключения файлов (регулярные выражения) | -e "test\\.js$" "spec\\.js$" | | --comment | -c | Заголовочный комментарий для бандла | -c "Production bundle" | | --log | -l | Включить подробное логирование | -l | | --dry-run | | Показать что будет сделано без реального создания файлов | --dry-run | | --version | -V | Показать версию | -V | | --help | -h | Показать справку | -h |

Подкоманды

info Показать информацию о пакете и примеры использования:

tsb info

init Создать пример конфигурационного файла:

tsb init

🎯 Примеры использования

Пример 1: Простое объединение

# Объединить все файлы из src в единые бандлы
tsb ./src --js-file ./dist/app.js --dts-file ./dist/app.d.ts

Пример 2: С исключением тестовых файлов

# Исключить тестовые файлы
tsb ./src \
  --js-file ./dist/bundle.js \
  --dts-file ./dist/bundle.d.ts \
  --exclude "test\\.js$" "spec\\.js$" "\\.test\\."

Пример 3: С заголовочным комментарием

# Добавить комментарий в начало файла
tsb ./src \
  --js-file ./dist/bundle.js \
  --comment "Production bundle v1.0.0\nGenerated: $(date)"

Пример 4: Только JavaScript файлы

# Объединить только .js файлы
tsb ./src --js-file ./dist/scripts.js

Пример 5: Проверка без выполнения

# Показать что будет сделано без реального выполнения
tsb ./src --js-file ./dist/bundle.js --dry-run

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

После выполнения tsb init создается файл bundle.config.json:

{
  "inputDir": "./src",
  "outputJsFile": "./dist/bundle.js",
  "outputDtsFile": "./dist/bundle.d.ts",
  "excludePatterns": ["test\\.js$", "spec\\.js$", "\\.test\\."],
  "headerComment": "Generated bundle\nDo not edit manually"
}

Для использования конфигурационного файла можно создать простой скрипт:

// build.js
import { bundleFiles } from 'typescript-bundler';
import config from './bundle.config.json'

await bundleFiles(config);

🔧 Использование как модуля

Пакет также можно использовать программно:

import { FileBundler } from 'typescript-bundler';

// Создание экземпляра бандлера
const bundler = new FileBundler({
  inputDir: './src',
  outputJsFile: './dist/bundle.js',
  outputDtsFile: './dist/bundle.d.ts',
  excludePatterns: [/test\.js$/, /spec\.js$/],
  headerComment: 'Custom bundle header',
  disableWarnings: false
});

// Запуск процесса объединения
await bundler.bundle();

Или с помощью экспортируемой функции:

import bundleFiles from 'typescript-bundler';

await bundleFiles({
  inputDir: './src',
  outputJsFile: './dist/bundle.js',
  outputDtsFile: './dist/bundle.d.ts',
  excludePatterns: [/test\.js$/],
  headerComment: 'Generated bundle'
});

📁 Структура выходных файлов

Выходные файлы содержат:

1. Заголовочный комментарий (если указан)
2. Содержимое всех исходных файлов с разделителями
3. Для каждого файла добавляется комментарий с его относительным путем

Пример выходного JS файла:

/*
Production bundle v1.0.0
Generated: 2024-01-15
*/

// ===== File: utils/math.js =====
export function sum(a, b) {
    return a + b;
}

// ===== File: utils/string.js =====
export function capitalize(str) {
    return str.charAt(0).toUpperCase() + str.slice(1);
}

🚨 Особенности и ограничения

Что делает бандлер:

• ✅ Рекурсивно обходит все поддиректории

• ✅ Объединяет все .js файлы в один файл

• ✅ Объединяет все .d.ts файлы в один файл

• ✅ Поддерживает регулярные выражения для исключения файлов

• ✅ Автоматически создает выходные директории

• ✅ Добавляет разделители между файлами

• ✅ Поддерживает заголовочные комментарии

Что НЕ делает бандлер:

• ❌ Не минифицирует код

• ❌ Не разрешает зависимости между файлами

• ❌ Не транспилирует код (использует исходные файлы как есть)

• ❌ Не обрабатывает импорты/экспорты между файлами

• ❌ Не проверяет синтаксис исходных файлов

🔍 Регулярные выражения для исключения

Примеры паттернов для исключения файлов:

| Паттерн | Описание | Примеры файлов | |---------|----------|----------------| | test\\.js$ | Файлы заканчивающиеся на test.js | app.test.js, utils.test.js | | spec\\.js$ | Файлы заканчивающиеся на spec.js | component.spec.js | | \\.test\\. | Файлы содержащие .test. в имени | file.test.js, test.utils.js | | ^_ | Файлы начинающиеся с подчеркивания | _internal.js, _test.js | | mock | Файлы содержащие mock в имени | user.mock.js, mockData.js |

⚡ Производительность

Бандлер оптимизирован для работы с большими проектами:

• Использует потоковое чтение файлов
• Минимальное использование памяти
• Быстрая рекурсивная обработка директорий

Обработка ошибок

При возникновении ошибок бандлер:

1. Выводит понятное сообщение об ошибке
2. Указывает на проблемный файл или директорию
3. Завершает работу с ненулевым кодом возврата

🤝 Вклад в проект

1. Форкните репозиторий
2. Создайте ветку для вашей функции (git checkout -b feature/amazing-feature)
3. Закоммитьте изменения (git commit -m 'Add amazing feature')
4. Запушьте в ветку (git push origin feature/amazing-feature)
5. Откройте Pull Request

📄 Лицензия

Этот проект распространяется под лицензией GPL-3.0-only. См. файл LICENSE для получения дополнительной информации.

📞 Поддержка

• Issues: GitHub Issues
• Автор: Маг Ильяс DOMA (MagIlyasDOMA)

🎉 Благодарности

Спасибо за использование TypeScript Bundler! Если у вас есть предложения по улучшению, создавайте issue или pull request.

Примечание: Этот инструмент предназначен для простого объединения файлов. Для сложных сценариев сборки рассмотрите использование специализированных инструментов, таких как Webpack, Rollup или esbuild.