打包器

.
├── index.tsx
├── Component.tsx
└── out
    └── index.js

// out/index.js
// ...
// 约 2 万行代码
// 包含 `react-dom/client` 及所有依赖的内容
// 这里定义了 $jsxDEV 和 $createRoot 函数

// Component.tsx
function Component(props) {
  return $jsxDEV(
    "h1",
    {
      children: props.message,
    },
    undefined,
    false,
    undefined,
    this,
  );
}

// index.tsx
var rootNode = document.getElementById("root");
var root = $createRoot(rootNode);
root.render(
  $jsxDEV(
    Component,
    {
      message: "Sup!",
    },
    undefined,
    false,
    undefined,
    this,
  ),
);

bun build ./index.tsx --outdir ./out --watch

const result = await Bun.build({
  entrypoints: ["/app/index.ts"],
  files: {
    "/app/index.ts": `
      import { greet } from "./greet.ts";
      console.log(greet("World"));
    `,
    "/app/greet.ts": `
      export function greet(name: string) {
        return "Hello, " + name + "!";
      }
    `,
  },
});

const output = await result.outputs[0].text();
console.log(output);

// 假设 ./src/config.ts 磁盘文件存在，含开发配置
await Bun.build({
  entrypoints: ["./src/index.ts"],
  files: {
    // 用生产配置覆盖 config.ts
    "./src/config.ts": `
      export const API_URL = "https://api.production.com";
      export const DEBUG = false;
    `,
  },
  outdir: "./dist",
});

// ./src/index.ts 磁盘存在，导入 "./generated.ts"
await Bun.build({
  entrypoints: ["./src/index.ts"],
  files: {
    // 提供 index.ts 导入的虚拟文件
    "./src/generated.ts": `
      export const BUILD_ID = "${crypto.randomUUID()}";
      export const BUILD_TIME = ${Date.now()};
    `,
  },
  outdir: "./dist",
});

const result = await Bun.build({
  entrypoints: ["./index.ts"],
});

for (const res of result.outputs) {
  // 可作为 Blob 处理
  await res.text();

  // Bun 设置 Content-Type 和 Etag 标头
  new Response(res);

  // 也可手动写入，但此时推荐使用 `outdir` 选项。
  Bun.write(path.join("out", res.path), res);
}

.
├── entry-a.ts
├── entry-b.ts
├── shared.ts
└── out
    ├── entry-a.js
    ├── entry-b.js
    └── chunk-dqmx6gc8.js

const { render } = await import("./markdown"); // keeps `render`
import("./telemetry").then(t => t.init()); // keeps `init`
const { parse } = require("./yaml"); // keeps `parse` (ES module targets only)
await import("./polyfill"); // keeps only side effects

await Bun.build({
  entrypoints: ["./index.tsx"],
  outdir: "./out",
  plugins: [
    /* ... */
  ],
});

// input.js
console.log(process.env.FOO);
console.log(process.env.BAZ);

// output.js
console.log("bar");
console.log("123");

FOO=bar BAZ=123 ACME_PUBLIC_URL=https://acme.com

console.log(process.env.FOO);
console.log(process.env.ACME_PUBLIC_URL);
console.log(process.env.BAZ);

console.log(process.env.FOO);
console.log("https://acme.com");
console.log(process.env.BAZ);

import _ from "lodash";
import { z } from "zod";

const value = z.string().parse("Hello world!");
console.log(_.upperCase(value));

import { z } from "zod";

// ...
// lodash 源码
// 包括 `_.upperCase` 函数

var value = z.string().parse("Hello world!");
console.log(_.upperCase(value));

.
├── index.tsx
└── out
    └── index.js

.
├── index.tsx
└── nested
    └── index.tsx
└── out
    ├── index.js
    └── nested
        └── index.js

.
├── index.tsx
└── out
    └── files
        └── index-a1b2c3d4.js

.
└── pages
  └── index.tsx
  └── settings.tsx

.
└── pages
  └── index.tsx
  └── settings.tsx
└── out
  └── index.js
  └── settings.js

var logo = "https://cdn.example.com/logo-a7305bdef.svg";

import { feature } from "bun:bundle";

if (feature("PREMIUM")) {
  // 仅 PREMIUM 标记启用时包含
  initPremiumFeatures();
}

if (feature("DEBUG")) {
  // 仅 DEBUG 标记启用时包含
  console.log("Debug mode");
}

import { feature } from "bun:bundle";
const mode = feature("PREMIUM") ? "premium" : "free";

var mode = "premium";

var mode = "free";

declare module "bun:bundle" {
  interface Registry {
    features: "DEBUG" | "PREMIUM" | "BETA_FEATURES";
  }
}

await Bun.build({
  entrypoints: ["./app.ts"],
  outdir: "./out",
  optimizeImports: ["antd", "@mui/material", "lodash-es"],
});

bun build ./src/index.ts --outdir ./dist --metafile-md=./dist/meta.md

bun build ./src/index.ts --outdir ./dist --metafile=./dist/meta.json --metafile-md=./dist/meta.md

// 布尔值 - 在结果对象中包含 metafile 字段
await Bun.build({
  entrypoints: ["./src/index.ts"],
  outdir: "./dist",
  metafile: true,
});

// 字符串 - 将 JSON metafile 写入指定路径
await Bun.build({
  entrypoints: ["./src/index.ts"],
  outdir: "./dist",
  metafile: "./dist/meta.json",
});

// 对象 - 指定 JSON 和 Markdown 输出路径
await Bun.build({
  entrypoints: ["./src/index.ts"],
  outdir: "./dist",
  metafile: {
    json: "./dist/meta.json",
    markdown: "./dist/meta.md",
  },
});

interface BuildOutput {
  outputs: BuildArtifact[];
  success: boolean;
  logs: Array<object>; // 详见文档
  metafile?: BuildMetafile; // 仅当 metafile: true 时存在
}

interface BuildArtifact extends Blob {
  kind: "entry-point" | "chunk" | "asset" | "sourcemap" | "bytecode";
  path: string;
  loader: Loader;
  hash: string | null;
  sourcemap: BuildArtifact | null;
}

const build = await Bun.build({
  /* */
});

for (const output of build.outputs) {
  await output.arrayBuffer(); // => ArrayBuffer
  await output.bytes(); // => Uint8Array
  await output.text(); // string
}

const build = await Bun.build({
  /* */
});

const artifact = build.outputs[0];

// 会自动设置 Content-Type 头
return new Response(artifact);

bun build ./cli.tsx --outfile mycli --compile
./mycli

try {
  const result = await Bun.build({
    entrypoints: ["./index.tsx"],
    outdir: "./out",
  });
} catch (e) {
  // TS 不允许在 catch 加类型注解，故用断言
  const error = e as AggregateError;
  console.error("构建失败");

  // 示例：内置格式化打印
  console.error(error);

  // 示例：序列化成 JSON 字符串打印
  console.error(JSON.stringify(error, null, 2));
}

class BuildMessage {
  name: string;
  position?: Position;
  message: string;
  level: "error" | "warning" | "info" | "debug" | "verbose";
}

class ResolveMessage extends BuildMessage {
  code: string;
  referrer: string;
  specifier: string;
  importKind: ImportKind;
}

const result = await Bun.build({
  entrypoints: ["./index.tsx"],
  outdir: "./out",
});

if (result.logs.length > 0) {
  console.warn("构建成功但有警告：");
  for (const message of result.logs) {
    // Bun 会美化打印消息对象
    console.warn(message);
  }
}

interface Bun {
  build(options: BuildOptions): Promise<BuildOutput>;
}

interface BuildConfig {
  entrypoints: string[]; // 入口文件数组
  outdir?: string; // 输出目录
  target?: Target; // 默认 "browser"
  /**
   * 输出模块格式，顶层 await 仅支持 "esm"
   *
   * 可选:
   * - "esm"
   * - "cjs" (**实验性**)
   * - "iife" (**实验性**)
   *
   * @default "esm"
   */
  format?: "esm" | "cjs" | "iife";
  /**
   * JSX 配置对象，控制 JSX 转换行为
   */
  jsx?: {
    runtime?: "automatic" | "classic";
    importSource?: string;
    factory?: string;
    fragment?: string;
    sideEffects?: boolean;
    development?: boolean;
  };
  naming?:
    | string
    | {
        chunk?: string;
        entry?: string;
        asset?: string;
      };
  root?: string; // project root
  splitting?: boolean; // default false, enable code splitting
  splitRequire?: boolean; // default true, with splitting and target "bun": require() of an ES module is a chunk too
  minChunkSize?: number; // default 0, also fold side-effect-free chunks smaller than this many source bytes
  modulePreload?: boolean; // default true, with splitting and target "browser": <link rel=modulepreload> the chunks an entrypoint or import() depends on
  plugins?: BunPlugin[];
  external?: string[];
  packages?: "bundle" | "external";
  publicPath?: string;
  define?: Record<string, string>;
  loader?: { [k in string]: Loader };
  sourcemap?: "none" | "linked" | "inline" | "external" | boolean; // 默认 "none"，true 相当于 "inline"
  /**
   * package.json 的 `exports` 条件，用于解析导入
   *
   * 等同于 CLI 中 `--conditions` 参数
   *
   * https://nodejs.org/api/packages.html#exports
   */
  conditions?: Array<string> | string;

  /**
   * 打包时环境变量处理方式
   *
   * 可选:
   * - "inline": 将 `process.env.FOO` 替换为实际值字符串字面量
   * - "disable": 禁用环境变量注入
   * - 以 "*" 结尾的字符串: 内联匹配前缀的环境变量，如 "MY_PUBLIC_*"
   */
  env?: "inline" | "disable" | `${string}*`;
  minify?:
    | boolean
    | {
        whitespace?: boolean;
        syntax?: boolean;
        identifiers?: boolean;
      };
  /**
   * 忽略无用代码消除相关注释和 package.json 中 "sideEffects" 设置，仅作为库注释错误的临时解决方案
   */
  ignoreDCEAnnotations?: boolean;
  /**
   * 即使 minify.whitespace 为 true，也强制保留 @__PURE__ 注释
   */
  emitDCEAnnotations?: boolean;
  /**
   * Emit a setter per property on bundled module namespace objects (default).
   * @deprecated set to `false` for getter-only namespace objects; this becomes
   * the only behavior in a future release.
   */
  deprecatedNamespaceObjectSetters?: boolean;

  /**
   * 生成字节码，可显著减少冷启动时间，但会增加体积和内存占用。
   *
   * 仅支持 CommonJS (`format: "cjs"`)，必须配合 `target: "bun"` 使用
   *
   * @default false
   */
  bytecode?: boolean;
  /**
   * How many levels of nested functions to compile to bytecode ahead of time
   * (a non-negative integer; `0` = only each module's top-level code).
   * Only used when `bytecode: true`.
   * @default undefined (all nested functions)
   */
  bytecodeDepth?: number;
  /**
   * Build-time optimizations for `bytecode` builds.
   */
  optimize?: {
    /**
     * Run JavaScriptCore's build-time optimization passes over the generated bytecode.
     * @default true
     */
    bytecode?: boolean;
  };
  /**
   * Add a banner to the bundled code such as "use client";
   */
  banner?: string;
  /**
   * 添加代码底部内容，如版权注释
   */
  footer?: string;

  /**
   * 移除匹配的函数调用
   */
  drop?: string[];

  /**
   * - true 时构建失败时拒绝并抛出 AggregateError；
   * - false 时返回 `{success: false}` 的 BuildOutput
   *
   * @default true
   */
  throw?: boolean;

  /**
   * 指定自定义 tsconfig.json 路径，用于路径解析
   * 等同于 CLI 的 `--tsconfig-override`
   */
  tsconfig?: string;

  outdir?: string;
}

interface BuildOutput {
  outputs: BuildArtifact[];
  success: boolean;
  logs: Array<BuildMessage | ResolveMessage>;
}

interface BuildArtifact extends Blob {
  path: string;
  loader: Loader;
  hash: string | null;
  kind: "entry-point" | "chunk" | "asset" | "sourcemap" | "bytecode";
  sourcemap: BuildArtifact | null;
}

type Loader =
  | "js"
  | "jsx"
  | "ts"
  | "tsx"
  | "css"
  | "json"
  | "jsonc"
  | "toml"
  | "yaml"
  | "text"
  | "file"
  | "napi"
  | "wasm"
  | "html";

interface BuildOutput {
  outputs: BuildArtifact[];
  success: boolean;
  logs: Array<BuildMessage | ResolveMessage>;
}

declare class ResolveMessage {
  readonly name: "ResolveMessage";
  readonly position: Position | null;
  readonly code: string;
  readonly message: string;
  readonly referrer: string;
  readonly specifier: string;
  readonly importKind:
    | "entry_point"
    | "stmt"
    | "require"
    | "import"
    | "dynamic"
    | "require_resolve"
    | "at"
    | "at_conditional"
    | "url"
    | "internal";
  readonly level: "error" | "warning" | "info" | "debug" | "verbose";

  toString(): string;
}