Bun JS HTML 및 정적 사이트

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

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 파일에 한 번만 포함됩니다.

플러그인

개발 서버는 플러그인을 지원합니다.

Tailwind CSS

TailwindCSS 를 사용하려면 bun-plugin-tailwind 플러그인을 설치하세요:

bash

# 또는 모든 npm 클라이언트
bun install --dev bun-plugin-tailwind

그런 다음 bunfig.toml 에 플러그인을 추가하세요:

toml

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

그런 다음 HTML 의 <link> 태그, CSS 의 @import 또는 JavaScript 의 가져오기를 통해 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 은 모든 일반적인 웹 자산을 자동으로 처리합니다:

스크립트 (<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

무엇이 처리되나요?

작동 방식

프론트엔드에 백엔드 추가