Настройка TypeScript-приложения с Bun

Если вы управляли TypeScript-проектами с Node.js, вы знаете эти трудности: установка ts-node или tsx, настройка этапа сборки, конфигурация скриптов, и только потом можно начинать писать код. Bun устраняет большую часть этих накладных расходов. Это современная среда выполнения JavaScript, которая запускает TypeScript-файлы напрямую, поставляется со встроенным менеджером пакетов и выступает в роли task runner’а — всё в одном инструменте. Это руководство проведёт вас через полную настройку TypeScript-проекта с Bun, чтобы вы могли перейти от нуля к запуску TypeScript за считанные минуты.

Что такое Bun и зачем использовать его для TypeScript?

Bun — это быстрая среда выполнения JavaScript, построенная на JavaScriptCore и написанная на Zig. Что делает её особенной для разработки на TypeScript, так это то, что она нативно транспилирует .ts и .tsx файлы во время выполнения — без отдельного этапа сборки. В отличие от комбинации Node.js + ts-node, Bun обрабатывает транспиляцию внутренне, что означает заметно более быстрое время запуска и более простой рабочий процесс разработки.

Помимо среды выполнения, Bun заменяет сразу несколько инструментов:

• Среда выполнения — выполняет TypeScript и JavaScript напрямую
• Менеджер пакетов — более быстрая альтернатива npm, yarn или pnpm
• Task runner — запускает скрипты, определённые в package.json

Создание нового TypeScript-проекта с Bun

Начните с установки Bun, затем создайте новый проект:

bun init

Bun предложит вам указать точку входа. Используйте src/index.ts для поддержания порядка:

entry point (index.ts): src/index.ts

Это создаст минимальную структуру проекта:

my-app/
├── src/
│   └── index.ts
├── package.json
├── tsconfig.json
└── bun.lock

Файл bun.lock — это файл блокировки зависимостей Bun, используемый менеджером пакетов Bun для обеспечения согласованных установок.

Установка определений типов Bun

Если @types/bun ещё не присутствует в вашем проекте, установите его как dev-зависимость для получения корректного IntelliSense и проверки типов для специфичных API Bun:

bun add -d @types/bun

Это даст вам типизированный доступ к встроенным API Bun, таким как Bun.serve(), Bun.file() и bun:sqlite. Смотрите официальную документацию Bun по TypeScript для получения дополнительной информации.

Рекомендуемый tsconfig.json для проектов Bun

Bun работает и без tsconfig.json, но он вам понадобится для поддержки IDE и проверки типов. Ключевая настройка для конфигурации TypeScript в Bun — это "moduleResolution": "bundler", которая согласуется с тем, как Bun разрешает модули внутренне.

Другие важные опции для включения:

• "target": "ESNext" и "lib": ["ESNext"] — использование современных возможностей JavaScript
• "strict": true — раннее обнаружение ошибок
• "noEmit": true — Bun обрабатывает выполнение, поэтому скомпилированный вывод не нужен
• "verbatimModuleSyntax": true — обеспечивает чистые импорты только типов
• "allowImportingTsExtensions": true — позволяет импортировать .ts файлы с их расширениями

Вот полный пример:

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "lib": ["ESNext"],
    "strict": true,
    "noEmit": true,
    "verbatimModuleSyntax": true,
    "allowImportingTsExtensions": true,
    "skipLibCheck": true
  },
  "include": ["src"]
}

⚠️ Важно: Транспилятор Bun удаляет аннотации типов для скорости — он не выполняет полную проверку типов во время выполнения. Запускайте bunx tsc --noEmit отдельно во время разработки или в CI для обнаружения ошибок типизации.

Запуск TypeScript-файлов и управление скриптами

Запуск TypeScript-файла с Bun прост:

bun run src/index.ts

Для разработки с автоматическими перезапусками при изменении файлов используйте режим наблюдения:

bun --watch src/index.ts

Добавьте ваши обычные рабочие процессы в скрипты package.json:

{
  "scripts": {
    "dev": "bun --watch src/index.ts",
    "start": "bun run src/index.ts",
    "typecheck": "bunx tsc --noEmit"
  }
}

Bun запускает эти скрипты напрямую — дополнительный task runner не нужен.

Что ещё охватывает Bun

Как только настройка вашего TypeScript-проекта с Bun завершена, у вас есть доступ к нескольким встроенным возможностям без добавления зависимостей:

• Test runner — bun test поддерживает Jest-совместимый API из коробки
• Бандлер — bun build обрабатывает бандлинг фронтенд-ресурсов
• SQLite — bun:sqlite предоставляет нативный типизированный интерфейс базы данных

Эти возможности не требуются для базовой настройки, но они доступны в тот момент, когда они вам понадобятся. Вы можете изучить полный набор функций в официальной документации Bun.

Заключение

Основное изменение при использовании TypeScript с Bun — это принятие того, что среда выполнения обрабатывает транспиляцию, в то время как tsc обрабатывает безопасность типов — это отдельные задачи. Как только это становится понятно, рабочий процесс становится чистым: инициализируйте проект, установите @types/bun при необходимости, настройте ваш tsconfig.json с разрешением модулей в стиле бандлера и запускайте ваши TypeScript-файлы напрямую. Никакого конвейера сборки для поддержки, никаких дополнительных инструментов для установки.

Часто задаваемые вопросы

Complete picture for complete understanding

Capture every clue your frontend is leaving so you can instantly get to the root cause of any issue with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data.

Check our GitHub repo and join the thousands of developers in our community.