Bun JS HTML & static sites

Бандлер Bun имеет первоклассную поддержку HTML. Создавайте статические сайты лендинги и веб-приложения без какой-либо конфигурации. Просто укажите Bun на ваш HTML-файл и он обработает все остальное.

html

<!doctype html>
<html>
  <head>
    <link rel="stylesheet" href="./styles.css" />
    <script src="./app.ts" type="module"></script>
  </head>
  <body>
    <img src="./logo.png" />
  </body>
</html>

Для начала передайте HTML-файлы в bun.

bash

bun ./index.html

Bun v1.3.3
ready in 6.62ms
→ http://localhost:3000/
Press h + Enter to show shortcuts

Dev-сервер Bun предоставляет мощные функции без какой-либо конфигурации:

Автоматическое связывание - Связывает и обслуживает ваш HTML JavaScript и CSS
Поддержка нескольких точек входа - Обрабатывает несколько HTML-точек входа и glob-точек входа
Современный JavaScript - Поддержка TypeScript и JSX из коробки
Умная конфигурация - Читает tsconfig.json для путей опций JSX экспериментальных декораторов и многого другого
Плагины - Плагины для TailwindCSS и других
ESM и CommonJS - Используйте ESM и CommonJS в ваших JavaScript TypeScript и JSX файлах
Связывание и минификация CSS - Связывает CSS из тегов <link> и операторов @import
Управление активами - Автоматическое копирование и хеширование изображений и активов; Переписывание путей к активам в JavaScript CSS и HTML

Одностраничные приложения (SPA)

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

bash

bun index.html

Bun v1.3.3
ready in 6.62ms
→ http://localhost:3000/
Press h + Enter to show shortcuts

Ваш React или другое SPA будет работать из коробки — не требуется никакой конфигурации. Все маршруты такие как /about /users/123 и т.д. будут обслуживать один и тот же HTML-файл позволяя вашему клиентскому роутеру обрабатывать навигацию.

html

<!doctype html>
<html>
  <head>
    <title>My SPA</title>
    <script src="./app.tsx" type="module"></script>
  </head>
  <body>
    <div id="root"></div>
  </body>
</html>

Многостраничные приложения (MPA)

Некоторые проекты имеют несколько отдельных маршрутов или HTML-файлов в качестве точек входа. Для поддержки нескольких точек входа передайте их все в bun:

bash

bun ./index.html ./about.html

txt

Bun v1.3.3
ready in 6.62ms
→ http://localhost:3000/
Routes:
  / ./index.html
  /about ./about.html
Press h + Enter to show shortcuts

Это будет обслуживать:

index.html на /
about.html на /about

Glob-паттерны

Для указания нескольких файлов вы можете использовать glob-паттерны которые заканчиваются на .html:

bash

bun ./**/*.html

Bun v1.3.3
ready in 6.62ms
→ http://localhost:3000/
Routes:
  / ./index.html
  /about ./about.html
Press h + Enter to show shortcuts

Нормализация путей

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

bash

bun ./index.html ./about/index.html ./about/foo/index.html

Bun v1.3.3
ready in 6.62ms
→ http://localhost:3000/
Routes:
  / ./index.html
  /about ./about/index.html
  /about/foo ./about/foo/index.html
Press h + Enter to show shortcuts

JavaScript TypeScript и JSX

Транспайлер Bun изначально поддерживает JavaScript TypeScript и JSX. Узнайте больше о загрузчиках в Bun.

NOTE

Транспайлер Bun также используется во время выполнения.

ES Modules и CommonJS

Вы можете использовать ESM и CJS в ваших JavaScript TypeScript и JSX файлах. Bun будет обрабатывать транспиляцию и связывание автоматически.

Нет предварительной сборки или отдельного шага оптимизации. Все делается одновременно.

Узнайте больше о разрешении модулей в Bun.

CSS

Парсер CSS Bun также реализован изначально (около 58 000 строк кода на Zig).

Это также CSS-бандлер. Вы можете использовать @import в ваших CSS-файлах для импорта других CSS-файлов.

Например:

css

@import "./abc.css";

.container {
  background-color: blue;
}

css

body {
  background-color: red;
}

Это выводит:

css

body {
  background-color: red;
}

.container {
  background-color: blue;
}

Ссылка на локальные активы в CSS

Вы можете ссылаться на локальные активы в ваших CSS-файлах.

css

body {
  background-image: url("./logo.png");
}

Это скопирует ./logo.png в выходную директорию и перепишет путь в CSS-файле для включения хеша содержимого.

css

body {
  background-image: url("./logo-[ABC123].png");
}

Импорт CSS в JavaScript

Для связывания CSS-файла с JavaScript-файлом вы можете импортировать его в ваш JavaScript-файл.

import "./styles.css";
import "./more-styles.css";

Это генерирует ./app.css и ./app.js в выходной директории. Все CSS-файлы импортируемые из JavaScript будут связаны в один CSS-файл для каждой точки входа. Если вы импортируете один и тот же CSS-файл из нескольких JavaScript-файлов он будет включен только один раз в выходной CSS-файл.

Плагины

Dev-сервер поддерживает плагины.

Tailwind CSS

Для использования TailwindCSS установите плагин bun-plugin-tailwind:

bash

# Или любой npm-клиент
bun install --dev bun-plugin-tailwind

Затем добавьте плагин в ваш bunfig.toml:

toml

[serve.static]
plugins = ["bun-plugin-tailwind"]

Затем ссылайтесь на TailwindCSS в вашем HTML через тег <link> @import в CSS или импорт в JavaScript.

index.html">

```html
<!-- Ссылка на TailwindCSS в вашем HTML -->
<link rel="stylesheet" href="tailwindcss" />
```

styles.css">

```css title="styles.css" icon="file-code"
@import "tailwindcss";
```

app.ts">

```ts 
import "tailwindcss";
```

Встроенные переменные окружения

Bun может заменять ссылки process.env.* в вашем JavaScript и TypeScript их фактическими значениями во время сборки. Это полезно для внедрения конфигурации такой как URL API или флаги функций в ваш фронтенд-код.

Dev-сервер (время выполнения)

Для встраивания переменных окружения при использовании bun ./index.html настройте опцию env в вашем bunfig.toml:

toml

[serve.static]
env = "PUBLIC_*"  # только переменные окружения начинающиеся с PUBLIC_ (рекомендуется)
# env = "inline"  # встраивать все переменные окружения
# env = "disable" # отключить замену переменных окружения (по умолчанию)

NOTE

Это работает только с литеральными ссылками `process.env.FOO` не `import.meta.env` или косвенным доступом как `const env = process.env; env.FOO`.

Если переменная окружения не установлена вы можете увидеть ошибки времени выполнения такие как ReferenceError: process is not defined в браузере.

Затем запустите dev-сервер:

bash

PUBLIC_API_URL=https://api.example.com bun ./index.html

Сборка для продакшена

При сборке статического HTML для продакшена используйте опцию env для встраивания переменных окружения:

CLI">

```bash
# Встроить все переменные окружения
bun build ./index.html --outdir=dist --env=inline

# Только переменные окружения с определенным префиксом (рекомендуется)
bun build ./index.html --outdir=dist --env=PUBLIC_*
```

API">

```ts
# Встроить все переменные окружения
await Bun.build({
  entrypoints: ["./index.html"],
  outdir: "./dist",
  env: "inline", // [!code highlight]
});

# Только переменные окружения с определенным префиксом (рекомендуется)
await Bun.build({
  entrypoints: ["./index.html"],
  outdir: "./dist",
  env: "PUBLIC_*", // [!code highlight]
});
```

Пример

Дан этот исходный файл:

const apiUrl = process.env.PUBLIC_API_URL;
console.log(`API URL: ${apiUrl}`);

И запуск с PUBLIC_API_URL=https://api.example.com:

bash

PUBLIC_API_URL=https://api.example.com bun build ./index.html --outdir=dist --env=PUBLIC_*

Связанный вывод будет содержать:

const apiUrl = "https://api.example.com";
console.log(`API URL: ${apiUrl}`);

Эхо консольных логов из браузера в терминал

Dev-сервер Bun поддерживает потоковую передачу консольных логов из браузера в терминал.

Для включения передайте CLI-флаг --console.

bash

bun ./index.html --console

Bun v1.3.3
ready in 6.62ms
→ http://localhost:3000/
Press h + Enter to show shortcuts

Каждый вызов console.log или console.error будет транслироваться в терминал который запустил сервер. Это полезно для просмотра ошибок из браузера в том же месте где вы запускаете сервер. Это также полезно для AI-агентов которые наблюдают за выводом терминала.

Внутренне это использует существующее WebSocket-соединение от горячей перезагрузки модулей для отправки логов.

Редактирование файлов в браузере

Frontend dev-сервер Bun имеет поддержку Automatic Workspace Folders в Chrome DevTools что позволяет сохранять изменения файлов в браузере.

Клавиатурные сокращения

Пока сервер запущен:

o + Enter - Открыть в браузере
c + Enter - Очистить консоль
q + Enter (или Ctrl+C) - Выйти из сервера

Сборка для продакшена

Когда вы готовы к развертыванию используйте bun build для создания оптимизированных продакшен-бандлов:

CLI">

```bash
bun build ./index.html --minify --outdir=dist
```

API">

```ts
await Bun.build({
  entrypoints: ["./index.html"],
  outdir: "./dist",
  minify: true,
});
```

Режим наблюдения

Вы можете запустить bun build --watch для наблюдения за изменениями и автоматической пересборки. Это хорошо работает для разработки библиотек.

Plugin API

Нужен больший контроль? Настройте бандлер через JavaScript API и используйте встроенный HTMLRewriter от Bun для предварительной обработки HTML.

await Bun.build({
  entrypoints: ["./index.html"],
  outdir: "./dist",
  minify: true,

  plugins: [
    {
      // Плагин который делает каждый HTML-тег в нижнем регистре
      name: "lowercase-html-plugin",
      setup({ onLoad }) {
        const rewriter = new HTMLRewriter().on("*", {
          element(element) {
            element.tagName = element.tagName.toLowerCase();
          },
          text(element) {
            element.replace(element.text.toLowerCase());
          },
        });

        onLoad({ filter: /\.html$/ }, async args => {
          const html = await Bun.file(args.path).text();

          return {
            // Бандлер Bun будет сканировать HTML для тегов <script> тегов <link rel="stylesheet"> и других активов
            // и связывать их автоматически
            contents: rewriter.transform(html),
            loader: "html",
          };
        });
      },
    },
  ],
});

Что обрабатывается?

Bun автоматически обрабатывает все распространенные веб-активы:

Скрипты (<script src>) обрабатываются через бандлер JavaScript/TypeScript/JSX Bun
Таблицы стилей (<link rel="stylesheet">) обрабатываются через парсер и бандлер CSS Bun
Изображения (<img> <picture>) копируются и хешируются
Медиа (<video> <audio> <source>) копируются и хешируются
Любой тег <link> с атрибутом href указывающим на локальный файл переписывается в новый путь и хешируется

Все пути разрешаются относительно вашего HTML-файла что упрощает организацию вашего проекта как угодно.

Как это работает

Это небольшая обертка вокруг поддержки Bun для импортов HTML в JavaScript.

Добавление бэкенда к вашему фронтенду

Для добавления бэкенда к вашему фронтенду вы можете использовать опцию "routes" в Bun.serve.

Узнайте больше в документации по полнофункциональной разработке.

Одностраничные приложения (SPA) ​

Многостраничные приложения (MPA) ​

Glob-паттерны ​

Нормализация путей ​

JavaScript TypeScript и JSX ​

ES Modules и CommonJS ​

CSS ​

Ссылка на локальные активы в CSS ​

Импорт CSS в JavaScript ​

Плагины ​

Tailwind CSS ​

index.html"> ​

styles.css"> ​

app.ts"> ​

Встроенные переменные окружения ​

Dev-сервер (время выполнения) ​

Сборка для продакшена ​

CLI"> ​

API"> ​

Пример ​

Эхо консольных логов из браузера в терминал ​

Редактирование файлов в браузере ​

Клавиатурные сокращения ​

Сборка для продакшена ​

CLI"> ​

API"> ​

Режим наблюдения ​

Plugin API ​

Что обрабатывается? ​

Как это работает ​

Добавление бэкенда к вашему фронтенду ​

Одностраничные приложения (SPA)

Многостраничные приложения (MPA)

Glob-паттерны

Нормализация путей

JavaScript TypeScript и JSX

ES Modules и CommonJS

CSS

Ссылка на локальные активы в CSS

Импорт CSS в JavaScript

Плагины

Tailwind CSS

index.html">

styles.css">

app.ts">

Встроенные переменные окружения

Dev-сервер (время выполнения)

Сборка для продакшена

CLI">

API">

Пример

Эхо консольных логов из браузера в терминал

Редактирование файлов в браузере

Клавиатурные сокращения

Сборка для продакшена

CLI">

API">

Режим наблюдения

Plugin API

Что обрабатывается?

Как это работает

Добавление бэкенда к вашему фронтенду