Bun JS HTML & sites statiques

Le bundler de Bun prend en charge nativement le HTML. Construisez des sites statiques, des pages de destination et des applications web sans configuration. Pointez simplement Bun vers votre fichier HTML et il gère tout le reste.

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>

Pour commencer, passez des fichiers HTML à bun.

bash

bun ./index.html

Bun v1.3.3
prêt en 6.62ms
→ http://localhost:3000/
Appuyez sur h + Entrée pour afficher les raccourcis

Le serveur de développement de Bun fournit des fonctionnalités puissantes sans configuration :

Bundling automatique - Bundle et sert votre HTML, JavaScript et CSS
Prise en charge multi-entrée - Gère plusieurs points d'entrée HTML et des points d'entrée glob
JavaScript moderne - Prise en charge de TypeScript & JSX nativement
Configuration intelligente - Lit tsconfig.json pour les chemins, les options JSX, les décorateurs expérimentaux, et plus encore
Plugins - Plugins pour TailwindCSS et plus encore
ESM & CommonJS - Utilisez ESM et CommonJS dans vos fichiers JavaScript, TypeScript et JSX
Bundling & minification CSS - Bundle le CSS des balises <link> et des instructions @import
Gestion des assets - Copie et hachage automatiques des images et assets ; Réécriture des chemins d'assets dans JavaScript, CSS et HTML

Applications monopages (SPA)

Lorsque vous passez un seul fichier .html à Bun, Bun l'utilisera comme route de fallback pour tous les chemins. Cela le rend parfait pour les applications monopages qui utilisent le routage côté client :

bash

bun index.html

Bun v1.3.3
prêt en 6.62ms
→ http://localhost:3000/
Appuyez sur h + Entrée pour afficher les raccourcis

Votre React ou autre SPA fonctionnera nativement — aucune configuration nécessaire. Toutes les routes comme /about, /users/123, etc. serviront le même fichier HTML, permettant à votre routeur côté client de gérer la navigation.

html

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

Applications multipages (MPA)

Certains projets ont plusieurs routes ou fichiers HTML séparés comme points d'entrée. Pour prendre en charge plusieurs points d'entrée, passez-les tous à bun :

bash

bun ./index.html ./about.html

txt

Bun v1.3.3
prêt en 6.62ms
→ http://localhost:3000/
Routes :
  / ./index.html
  /about ./about.html
Appuyez sur h + Entrée pour afficher les raccourcis

Cela servira :

index.html à /
about.html à /about

Motifs glob

Pour spécifier plusieurs fichiers, vous pouvez utiliser des motifs glob qui se terminent par .html :

bash

bun ./**/*.html

Bun v1.3.3
prêt en 6.62ms
→ http://localhost:3000/
Routes :
  / ./index.html
  /about ./about.html
Appuyez sur h + Entrée pour afficher les raccourcis

Normalisation des chemins

Le chemin de base est choisi à partir du préfixe commun le plus long parmi tous les fichiers.

bash

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

Bun v1.3.3
prêt en 6.62ms
→ http://localhost:3000/
Routes :
  / ./index.html
  /about ./about/index.html
  /about/foo ./about/foo/index.html
Appuyez sur h + Entrée pour afficher les raccourcis

JavaScript, TypeScript et JSX

Le transpileur de Bun implémente nativement la prise en charge de JavaScript, TypeScript et JSX. Pour en savoir plus sur les loaders dans Bun.

NOTE

Le transpileur de Bun est également utilisé au moment de l'exécution.

Modules ES & CommonJS

Vous pouvez utiliser ESM et CJS dans vos fichiers JavaScript, TypeScript et JSX. Bun gérera la transpilation et le bundling automatiquement.

Il n'y a pas de pré-construction ou d'étape d'optimisation séparée. Tout est fait en même temps.

Pour en savoir plus sur la résolution de modules dans Bun.

CSS

L'analyseur CSS de Bun est également implémenté nativement (environ 58 000 lignes de Zig).

C'est aussi un bundler CSS. Vous pouvez utiliser @import dans vos fichiers CSS pour importer d'autres fichiers CSS.

Par exemple :

css

@import "./abc.css";

.container {
  background-color: blue;
}

css

body {
  background-color: red;
}

Cela produit :

css

body {
  background-color: red;
}

.container {
  background-color: blue;
}

Référencer des assets locaux dans CSS

Vous pouvez référencer des assets locaux dans vos fichiers CSS.

css

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

Cela copiera ./logo.png dans le répertoire de sortie et réécrira le chemin dans le fichier CSS pour inclure un hachage de contenu.

css

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

Importer du CSS dans JavaScript

Pour associer un fichier CSS à un fichier JavaScript, vous pouvez l'importer dans votre fichier JavaScript.

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

Cela génère ./app.css et ./app.js dans le répertoire de sortie. Tous les fichiers CSS importés depuis JavaScript seront bundle dans un seul fichier CSS par point d'entrée. Si vous importez le même fichier CSS depuis plusieurs fichiers JavaScript, il ne sera inclus qu'une seule fois dans le fichier CSS de sortie.

Plugins

Le serveur de développement prend en charge les plugins.

Tailwind CSS

Pour utiliser TailwindCSS, installez le plugin bun-plugin-tailwind :

bash

# Ou n'importe quel client npm
bun install --dev bun-plugin-tailwind

Ensuite, ajoutez le plugin à votre bunfig.toml :

toml

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

Ensuite, référencez TailwindCSS dans votre HTML via une balise <link>, @import dans CSS, ou importez dans JavaScript.

html

<!-- Référencez TailwindCSS dans votre HTML -->
<link rel="stylesheet" href="tailwindcss" />

css

@import "tailwindcss";

import "tailwindcss";

Variables d'environnement inline

Bun peut remplacer les références process.env.* dans votre JavaScript et TypeScript par leurs valeurs réelles au moment de la construction. Cela est utile pour injecter des configurations comme des URL d'API ou des feature flags dans votre code frontend.

Serveur de développement (runtime)

Pour inline les variables d'environnement lors de l'utilisation de bun ./index.html, configurez l'option env dans votre bunfig.toml :

toml

[serve.static]
env = "PUBLIC_*"  # uniquement les variables d'environnement commençant par PUBLIC_ (recommandé)
# env = "inline"  # inline toutes les variables d'environnement
# env = "disable" # désactiver le remplacement des variables d'environnement (par défaut)

NOTE

Cela fonctionne uniquement avec les références littérales `process.env.FOO`, pas `import.meta.env` ou l'accès indirect comme `const env = process.env; env.FOO`.

Si une variable d'environnement n'est pas définie, vous pouvez voir des erreurs d'exécution comme ReferenceError: process is not defined dans le navigateur.

Ensuite, exécutez le serveur de développement :

bash

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

Construire pour la production

Lors de la construction de HTML statique pour la production, utilisez l'option env pour inline les variables d'environnement :

bash

# Inline toutes les variables d'environnement
bun build ./index.html --outdir=dist --env=inline

# Uniquement les variables d'environnement avec un préfixe spécifique (recommandé)
bun build ./index.html --outdir=dist --env=PUBLIC_*

// Inline toutes les variables d'environnement
await Bun.build({
  entrypoints: ["./index.html"],
  outdir: "./dist",
  env: "inline", 
});

// Uniquement les variables d'environnement avec un préfixe spécifique (recommandé)
await Bun.build({
  entrypoints: ["./index.html"],
  outdir: "./dist",
  env: "PUBLIC_*", 
});

Exemple

Étant donné ce fichier source :

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

Et exécution avec PUBLIC_API_URL=https://api.example.com :

bash

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

La sortie bundle contiendra :

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

Renvoyer les logs console du navigateur vers le terminal

Le serveur de développement de Bun prend en charge le streaming des logs console du navigateur vers le terminal.

Pour activer, passez l'option CLI --console.

bash

bun ./index.html --console

Bun v1.3.3
prêt en 6.62ms
→ http://localhost:3000/
Appuyez sur h + Entrée pour afficher les raccourcis

Chaque appel à console.log ou console.error sera diffusé au terminal qui a démarré le serveur. Cela est utile pour voir les erreurs du navigateur au même endroit où vous exécutez votre serveur. Cela est également utile pour les agents IA qui surveillent la sortie du terminal.

En interne, cela réutilise la connexion WebSocket existante du rechargement de module à chaud pour envoyer les logs.

Modifier des fichiers dans le navigateur

Le serveur de développement frontend de Bun prend en charge les dossiers d'espace de travail automatiques dans Chrome DevTools, ce qui vous permet d'enregistrer des modifications dans les fichiers dans le navigateur.

Raccourcis clavier

Pendant l'exécution du serveur :

o + Entrée - Ouvrir dans le navigateur
c + Entrée - Effacer la console
q + Entrée (ou Ctrl+C) - Quitter le serveur

Construire pour la production

Lorsque vous êtes prêt à déployer, utilisez bun build pour créer des bundles de production optimisés :

bash

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

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

Mode watch

Vous pouvez exécuter bun build --watch pour surveiller les changements et reconstruire automatiquement. Cela fonctionne bien pour le développement de bibliothèques.

API de plugin

Besoin de plus de contrôle ? Configurez le bundler via l'API JavaScript et utilisez HTMLRewriter intégré de Bun pour pré-traiter le HTML.

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

  plugins: [
    {
      // Un plugin qui met chaque balise HTML en minuscules
      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 {
            // Le bundler de Bun scannera le HTML pour les balises <script>, les balises <link rel="stylesheet"> et autres assets
            // et les bundle automatiquement
            contents: rewriter.transform(html),
            loader: "html",
          };
        });
      },
    },
  ],
});

Qu'est-ce qui est traité ?

Bun gère automatiquement tous les assets web courants :

Scripts (<script src>) sont exécutés via le bundler JavaScript/TypeScript/JSX de Bun
Feuilles de style (<link rel="stylesheet">) sont exécutés via l'analyseur & bundler CSS de Bun
Images (<img>, <picture>) sont copiées et hachées
Médias (<video>, <audio>, <source>) sont copiés et hachés
Toute balise <link> avec un attribut href pointant vers un fichier local est réécrite vers le nouveau chemin et hachée

Tous les chemins sont résolus relativement à votre fichier HTML, ce qui facilite l'organisation de votre projet comme vous le souhaitez.

Comment cela fonctionne

Ceci est un petit wrapper autour de la prise en charge par Bun des importations HTML dans JavaScript.

Ajouter un backend à votre frontend

Pour ajouter un backend à votre frontend, vous pouvez utiliser l'option "routes" dans Bun.serve.

Pour en savoir plus dans la documentation full-stack.

Applications monopages (SPA) ​

Applications multipages (MPA) ​

Motifs glob ​

Normalisation des chemins ​

JavaScript, TypeScript et JSX ​

Modules ES & CommonJS ​

CSS ​

Référencer des assets locaux dans CSS ​

Importer du CSS dans JavaScript ​

Plugins ​

Tailwind CSS ​

Variables d'environnement inline ​

Serveur de développement (runtime) ​

Construire pour la production ​

Exemple ​

Renvoyer les logs console du navigateur vers le terminal ​

Modifier des fichiers dans le navigateur ​

Raccourcis clavier ​

Construire pour la production ​

Mode watch ​

API de plugin ​

Qu'est-ce qui est traité ? ​

Comment cela fonctionne ​

Ajouter un backend à votre frontend ​

Applications monopages (SPA)

Applications multipages (MPA)

Motifs glob

Normalisation des chemins

JavaScript, TypeScript et JSX

Modules ES & CommonJS

CSS

Référencer des assets locaux dans CSS

Importer du CSS dans JavaScript

Plugins

Tailwind CSS

Variables d'environnement inline

Serveur de développement (runtime)

Construire pour la production

Exemple

Renvoyer les logs console du navigateur vers le terminal

Modifier des fichiers dans le navigateur

Raccourcis clavier

Construire pour la production

Mode watch

API de plugin

Qu'est-ce qui est traité ?

Comment cela fonctionne

Ajouter un backend à votre frontend