Bun JS HTML と静的サイト

Bun のバンドラーは HTML をファーストクラスでサポートしています。設定なしで静的サイト、ランディングページ、Web アプリケーションを構築できます。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

Bun の開発サーバーは、設定なしで強力な機能を提供します：

自動バンドル - HTML、JavaScript、CSS をバンドルして提供
マルチエントリーサポート - 複数の HTML エントリーポイントとグロブエントリーポイントを処理
モダンな JavaScript - TypeScript と JSX をすぐにサポート
スマート設定 - tsconfig.json を読んでパス、JSX オプション、実験的デコレーターなどを処理
プラグイン - TailwindCSS などのプラグイン
ESM と CommonJS - JavaScript、TypeScript、JSX ファイルで ESM と CommonJS を使用
CSS バンドルとミニファイ - <link> タグと @import 文から CSS をバンドル
アセット管理 - 画像とアセットの自動コピーとハッシュ化；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 で about.html

グロブパターン

複数のファイルを指定するには、.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 モジュールと CommonJS

JavaScript、TypeScript、JSX ファイルで ESM と CJS を使用できます。Bun はトランスパイルとバンドルを自動的に処理します。

事前ビルドや個別の最適化ステップはありません。すべて同時に実行されます。

Bun のモジュール解決について詳しくはこちら。

CSS

Bun の CSS パーサーもネイティブに実装されています（約 58,000 行の Zig）。

これは CSS バンドラーでもあります。CSS ファイルで @import を使用して他の 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");
}

JavaScript での CSS のインポート

CSS ファイルを JavaScript ファイルに関連付けるには、JavaScript ファイルでインポートできます。

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

これにより、出力ディレクトリに ./app.css と ./app.js が生成されます。JavaScript からインポートされたすべての CSS ファイルは、エントリーポイントごとに単一の CSS ファイルにバンドルされます。複数の JavaScript ファイルから同じ CSS ファイルをインポートした場合、出力 CSS ファイルに 1 回のみ含まれます。

プラグイン

開発サーバーはプラグインをサポートしています。

Tailwind CSS

TailwindCSS を使用するには、bun-plugin-tailwind プラグインをインストールします：

bash

# または任意の npm クライアント
bun install --dev bun-plugin-tailwind

次に、bunfig.toml にプラグインを追加します：

toml

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

次に、<link> タグ、CSS 内の @import、または JavaScript 内のインポートで HTML 内の TailwindCSS を参照します。

index.html">

html

<!-- HTML で TailwindCSS を参照 -->
<link rel="stylesheet" href="tailwindcss" />

styles.css">

css

@import "tailwindcss";

app.ts">

import "tailwindcss";

インライン環境変数

Bun は、JavaScript と TypeScript 内の process.env.* 参照をビルド時に実際の値に置き換えることができます。これは、API URL や機能フラグなどの設定をフロントエンドコードに注入するのに役立ちます。

開発サーバー（ランタイム）

bun ./index.html を使用する際に環境変数をインライン化するには、bunfig.toml で env オプションを設定します：

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 のようなランタイムエラーが発生する可能性があります。

次に開発サーバーを実行します：

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">

// すべての環境変数をインライン
await Bun.build({
  entrypoints: ["./index.html"],
  outdir: "./dist",
  env: "inline", 
});

// 特定のプレフィックスを持つ環境変数のみインライン（推奨）
await Bun.build({
  entrypoints: ["./index.html"],
  outdir: "./dist",
  env: "PUBLIC_*", 
});

例

このソースファイルが与えられた場合：

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}`);

ブラウザのコンソールログをターミナルにエコー

Bun の開発サーバーは、ブラウザからターミナルにコンソールログをストリーミングすることをサポートしています。

有効にするには、--console CLI フラグを渡します。

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 接続を再利用してログを送信します。

ブラウザでファイルを編集

Bun のフロントエンド開発サーバーは、Chrome DevTools の自動ワークスペースフォルダーをサポートしており、ブラウザでファイルへの保存を可能にします。

キーボードショートカット

サーバーの実行中：

o + Enter - ブラウザで開く
c + Enter - コンソールをクリア
q + Enter（または Ctrl+C）- サーバーを終了

本番環境用にビルド

デプロイする準備ができたら、bun build を使用して最適化された本番環境バンドルを作成します：

CLI">

bash

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

API">

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

ウォッチモード

bun build --watch を実行して変更を監視し、自動的に再ビルドできます。これはライブラリ開発に最適です。

プラグイン API

より多くの制御が必要ですか？JavaScript API を通じてバンドラーを設定し、Bun 組み込みの HTMLRewriter を使用して 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 はすべての一般的な Web アセットを自動的に処理します：

スクリプト（<script src>）は Bun の JavaScript/TypeScript/JSX バンドラーで実行
スタイルシート（<link rel="stylesheet">）は Bun の CSS パーサーとバンドラーで実行
画像（<img>、<picture>）はコピーされてハッシュ化
メディア（<video>、<audio>、<source>）はコピーされてハッシュ化
ローカルファイルを指す href 属性を持つ任意の <link> タグは、新しいパスに書き換えられ、ハッシュ化

すべてのパスは HTML ファイルを基準に解決されるため、プロジェクトを自由に整理できます。

仕組み

これは、JavaScript 内の HTML インポートのサポートに関する Bun のラッパーです。

フロントエンドにバックエンドを追加

フロントエンドにバックエンドを追加するには、Bun.serve の "routes" オプションを使用できます。

詳しくはフルスタックドキュメントをご覧ください。

シングルページアプリ（SPA） ​

マルチページアプリ（MPA） ​

グロブパターン ​

パス正規化 ​

JavaScript、TypeScript、JSX ​

ES モジュールと CommonJS ​

CSS ​

CSS 内のローカルアセットの参照 ​

JavaScript での CSS のインポート ​

プラグイン ​

Tailwind CSS ​

index.html"> ​

styles.css"> ​

app.ts"> ​

インライン環境変数 ​

開発サーバー（ランタイム） ​

本番環境用にビルド ​

CLI"> ​

API"> ​

例 ​

ブラウザのコンソールログをターミナルにエコー ​

ブラウザでファイルを編集 ​

キーボードショートカット ​

本番環境用にビルド ​

CLI"> ​

API"> ​

ウォッチモード ​

プラグイン API ​

何が処理されるか ​

仕組み ​

フロントエンドにバックエンドを追加 ​

シングルページアプリ（SPA）

マルチページアプリ（MPA）

グロブパターン

パス正規化

JavaScript、TypeScript、JSX

ES モジュールと CommonJS

CSS

CSS 内のローカルアセットの参照

JavaScript での CSS のインポート

プラグイン

Tailwind CSS

index.html">

styles.css">

app.ts">

インライン環境変数

開発サーバー（ランタイム）

本番環境用にビルド

CLI">

API">

例

ブラウザのコンソールログをターミナルにエコー

ブラウザでファイルを編集

キーボードショートカット

本番環境用にビルド

CLI">

API">

ウォッチモード

プラグイン API

何が処理されるか

仕組み

フロントエンドにバックエンドを追加