Bun JS File Types

Сборщик 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.

Разбирает код и применяет набор преобразований по умолчанию, таких как устранение мёртвого кода и tree shaking. Обратите внимание, что 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.

var 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);

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

`sqlite`

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

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

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

Это поддерживается только когда target равен bun.

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

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

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

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

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

`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 как точек входа, а других ресурсов как внешних.

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

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 собирается вместе с HTML.

import "./styles.css";

Из импорта не возвращается никакого значения, он используется только для побочных эффектов.

Загрузчик `sh`

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

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

bun run ./script.sh

`file`

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

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

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`](/ru/bundler#naming).

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

Исправление ошибок импорта TypeScript

Если вы используете TypeScript, вы можете получить ошибку вроде этой:

// Ошибка TypeScript
// Cannot find module './logo.svg' or its corresponding type declarations.

Это можно исправить, создав файл *.d.ts в любом месте вашего проекта (любое имя подойдёт) со следующим содержимым:

declare module "*.svg" {
  const content: string;
  export default content;
}

Это говорит TypeScript, что любые импорты по умолчанию из .svg должны обрабатываться как строка.

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

js ​

jsx ​

ts ​

tsx ​

json ​

jsonc ​

toml ​

yaml ​

text ​

napi ​

sqlite ​

html ​

css ​

Загрузчик sh ​

file ​

Исправление ошибок импорта TypeScript ​

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

`js`

`jsx`

`ts`

`tsx`

`json`

`jsonc`

`toml`

`yaml`

`text`

`napi`

`sqlite`

`html`

`css`

Загрузчик `sh`

`file`

Исправление ошибок импорта TypeScript