Bun JS Loaders

Бандлер Bun реализует набор загрузчиков по умолчанию.

Как правило: и бандлер и время выполнения поддерживают одинаковый набор типов файлов из коробки.

.js .cjs .mjs .mts .cts .ts .tsx .jsx .css .json .jsonc .toml .yaml .yml .txt .wasm .node .html .sh

Bun использует расширение файла для определения того какой встроенный загрузчик следует использовать для разбора файла. Каждый загрузчик имеет имя такое как js tsx или json. Эти имена используются при создании плагинов которые расширяют Bun пользовательскими загрузчиками.

Вы можете явно указать какой загрузчик использовать используя атрибут импорта 'type'.

import my_toml from "./my_file" with { type: "toml" };
// или с динамическими импортами
const { default: my_toml } = await import("./my_file", { with: { type: "toml" } });

Встроенные загрузчики

`js`

Загрузчик JavaScript. По умолчанию для .cjs и .mjs.

Разбирает код и применяет набор стандартных преобразований таких как устранение мертвого кода и встряхивание дерева. Обратите внимание что Bun на данный момент не пытается понижать синтаксис.

`jsx`

Загрузчик JavaScript + JSX. По умолчанию для .js и .jsx.

То же что и загрузчик js но поддерживается синтаксис JSX. По умолчанию JSX понижается до обычного JavaScript; детали того как это делается зависят от опций компилятора jsx* в вашем tsconfig.json. Обратитесь к документации TypeScript по JSX для получения дополнительной информации.

`ts`

Загрузчик TypeScript. По умолчанию для .ts .mts и .cts.

Удаляет весь синтаксис TypeScript затем ведет себя идентично загрузчику js. Bun не выполняет проверку типов.

`tsx`

Загрузчик TypeScript + JSX. По умолчанию для .tsx.

Транспилирует как TypeScript так и JSX в обычный JavaScript.

`json`

Загрузчик JSON. По умолчанию для .json.

JSON файлы могут быть напрямую импортированы.

import pkg from "./package.json";
pkg.name; // => "my-package"

Во время связывания разобранный JSON встраивается в бандл как объект JavaScript.

const pkg = {
  name: "my-package",
  // ... другие поля
};

pkg.name;

Если .json файл передан как точка входа в бандлер он будет преобразован в .js модуль который делает export default разобранного объекта.

json

{
  "name": "John Doe",
  "age": 35,
  "email": "johndoe@example.com"
}

export default {
  name: "John Doe",
  age: 35,
  email: "johndoe@example.com",
};

`jsonc`

Загрузчик JSON с комментариями. По умолчанию для .jsonc.

JSONC (JSON с комментариями) файлы могут быть напрямую импортированы. Bun будет разбирать их удаляя комментарии и завершающие запятые.

import config from "./config.jsonc";
console.log(config);

Во время связывания разобранный JSONC встраивается в бандл как объект JavaScript идентично загрузчику json.

var config = {
  option: "value",
};

NOTE

Bun автоматически использует загрузчик `jsonc` для файлов `tsconfig.json` `jsconfig.json` `package.json` и `bun.lock`.

`toml`

Загрузчик TOML. По умолчанию для .toml.

TOML файлы могут быть напрямую импортированы. Bun будет разбирать их своим быстрым нативным парсером TOML.

import config from "./bunfig.toml";
config.logLevel; // => "debug"

// через атрибут импорта:
// import myCustomTOML from './my.config' with {type: "toml"};

Во время связывания разобранный TOML встраивается в бандл как объект JavaScript.

var config = {
  logLevel: "debug",
  // ...другие поля
};
config.logLevel;

Если .toml файл передан как точка входа он будет преобразован в .js модуль который делает export default разобранного объекта.

toml

name = "John Doe"
age = 35
email = "johndoe@example.com"

export default {
  name: "John Doe",
  age: 35,
  email: "johndoe@example.com",
};

`yaml`

Загрузчик YAML. По умолчанию для .yaml и .yml.

YAML файлы могут быть напрямую импортированы. Bun будет разбирать их своим быстрым нативным парсером YAML.

import config from "./config.yaml";
console.log(config);

// через атрибут импорта:
import data from "./data.txt" with { type: "yaml" };

Во время связывания разобранный YAML встраивается в бандл как объект JavaScript.

var config = {
  name: "my-app",
  version: "1.0.0",
  // ...другие поля
};

Если .yaml или .yml файл передан как точка входа он будет преобразован в .js модуль который делает export default разобранного объекта.

yaml

name: John Doe
age: 35
email: johndoe@example.com

export default {
  name: "John Doe",
  age: 35,
  email: "johndoe@example.com",
};

`text`

Текстовый загрузчик. По умолчанию для .txt.

Содержимое текстового файла читается и встраивается в бандл как строка. Текстовые файлы могут быть напрямую импортированы. Файл читается и возвращается как строка.

import contents from "./file.txt";
console.log(contents); // => "Hello, world!"

// Для импорта html файла как текста
// Атрибут "type" может использоваться для переопределения загрузчика по умолчанию.
import html from "./index.html" with { type: "text" };

При ссылке во время сборки содержимое встраивается в бандл как строка.

var contents = `Hello, world!`;
console.log(contents);

Если .txt файл передан как точка входа он будет преобразован в .js модуль который делает export default содержимого файла.

txt

Hello, world!

export default "Hello, world!";

`napi`

Загрузчик нативных аддонов. По умолчанию для .node.

Во времени выполнения нативные аддоны могут быть напрямую импортированы.

import addon from "./addon.node";
console.log(addon);

NOTE

В бандлере `.node` файлы обрабатываются с помощью файлового загрузчика.

`sqlite`

Загрузчик SQLite. Требует атрибут импорта with { "type": "sqlite" }.

Во времени выполнения и бандлере базы данных SQLite могут быть напрямую импортированы. Это загрузит базу данных используя bun:sqlite.

import db from "./my.db" with { type: "sqlite" };

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

Вы можете изменить это поведение с атрибутом "embed":

// встроить базу данных в бандл
import db from "./my.db" with { type: "sqlite", embed: "true" };

`html`

Загрузчик HTML. По умолчанию для .html.

Загрузчик html обрабатывает HTML файлы и связывает любые указанные активы. Он будет:

Связывать и хешировать указанные JavaScript файлы (<script src="...">)
Связывать и хешировать указанные CSS файлы (<link rel="stylesheet" href="...">)
Хешировать указанные изображения (<img src="...">)
Сохранять внешние URL (по умолчанию все что начинается с http:// или https://)

Например дан этот HTML файл:

html

<!DOCTYPE html>
<html>
  <body>
    <img src="./image.jpg" alt="Local image" />
    <img src="https://example.com/image.jpg" alt="External image" />
    <script type="module" src="./script.js"></script>
  </body>
</html>

Он выведет новый HTML файл со связанными активами:

html

<!DOCTYPE html>
<html>
  <body>
    <img src="./image-HASHED.jpg" alt="Local image" />
    <img src="https://example.com/image.jpg" alt="External image" />
    <script type="module" src="./output-ALSO-HASHED.js"></script>
  </body>
</html>

Под капотом он использует lol-html для извлечения тегов script и link как точек входа и других активов как внешних.

Список поддерживаемых HTML селекторов">

В настоящее время список селекторов:

audio[src]
iframe[src]
img[src]
img[srcset]
link:not([rel~='stylesheet']):not([rel~='modulepreload']):not([rel~='manifest']):not([rel~='icon']):not([rel~='apple-touch-icon'])[href]
link[as='font'][href], link[type^='font/'][href]
link[as='image'][href]
link[as='style'][href]
link[as='video'][href], link[as='audio'][href]
link[as='worker'][href]
link[rel='icon'][href], link[rel='apple-touch-icon'][href]
link[rel='manifest'][href]
link[rel='stylesheet'][href]
script[src]
source[src]
source[srcset]
video[poster]
video[src]

NOTE

Поведение загрузчика HTML в разных контекстах

Загрузчик html ведет себя по-разному в зависимости от того как он используется:

Статическая сборка: Когда вы запускаете bun build ./index.html Bun создает статический сайт со всеми связанными и хешированными активами.
Время выполнения: Когда вы запускаете bun run server.ts (где server.ts импортирует HTML файл) Bun связывает активы на лету во время разработки включая такие функции как горячая замена модулей.
Полнофункциональная сборка: Когда вы запускаете bun build --target=bun server.ts (где server.ts импортирует HTML файл) импорт разрешается в объект манифеста который Bun.serve использует для эффективного обслуживания предварительно связанных активов в продакшене.

`css`

Загрузчик CSS. По умолчанию для .css.

CSS файлы могут быть напрямую импортированы. Бандлер будет разбирать и связывать CSS файлы обрабатывая операторы @import и ссылки url().

import "./styles.css";

Во время связывания все импортированные CSS файлы связываются вместе в один .css файл в выходной директории.

css

.my-class {
  background: url("./image.png");
}

`sh`

Загрузчик Bun Shell. По умолчанию для .sh файлов.

Этот загрузчик используется для разбора скриптов Bun Shell. Он поддерживается только при запуске Bun поэтому недоступен в бандлере или во времени выполнения.

bash

bun run ./script.sh

`file`

Файловый загрузчик. По умолчанию для всех нераспознанных типов файлов.

Файловый загрузчик разрешает импорт как путь/URL к импортируемому файлу. Он обычно используется для ссылки на медиа или шрифтовые активы.

// logo.ts
import logo from "./logo.svg";
console.log(logo);

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

bash

bun run logo.ts
# Вывод: /path/to/project/logo.svg

В бандлере все немного иначе. Файл копируется в outdir как есть и импорт разрешается как относительный путь указывающий на скопированный файл.

// Выход
var logo = "./logo.svg";
console.log(logo);

Если указано значение для publicPath импорт будет использовать это значение как префикс для построения абсолютного пути/URL.

Public path	Разрешенный импорт
`""` (по умолчанию)	`/logo.svg`
`"/assets"`	`/assets/logo.svg`
`"https://cdn.example.com/"`	`https://cdn.example.com/logo.svg`

NOTE

Расположение и имя скопированного файла определяется значением `naming.asset`.

Этот загрузчик копируется в outdir как есть. Имя скопированного файла определяется с помощью значения naming.asset.

Встроенные загрузчики ​

js ​

jsx ​

ts ​

tsx ​

json ​

jsonc ​

toml ​

yaml ​

text ​

napi ​

sqlite ​

html ​

Список поддерживаемых HTML селекторов"> ​

css ​

sh ​

file ​

Встроенные загрузчики

`js`

`jsx`

`ts`

`tsx`

`json`

`jsonc`

`toml`

`yaml`

`text`

`napi`

`sqlite`

`html`

Список поддерживаемых HTML селекторов">

`css`

`sh`

`file`