bun-types 1.1.40 → 1.1.41-canary.20241220T140556

package/bun.d.ts

@@ -1596,7 +1596,7 @@ declare module "bun" {
 		define?: Record<string, string>;
 		// origin?: string; // e.g. http://mydomain.com
 		loader?: { [k in string]: Loader };
-		sourcemap?: "none" | "linked" | "inline" | "external" | "linked"; // default: "none", true -> "inline"
+		sourcemap?: "none" | "linked" | "inline" | "external" | "linked" | boolean; // default: "none", true -> "inline"
 		/**
 		 * package.json `exports` conditions used when resolving imports
 		 *
@@ -1690,6 +1690,15 @@ declare module "bun" {
 		 * Drop function calls to matching property accesses.
 		 */
 		drop?: string[];
+
+		/**
+		 * When set to `true`, the returned promise rejects with an AggregateError when a build failure happens.
+		 * When set to `false`, the `success` property of the returned object will be `false` when a build failure happens.
+		 *
+		 * This defaults to `false` in Bun 1.1 and will change to `true` in Bun 1.2
+		 * as most usage of `Bun.build` forgets to check for errors.
+		 */
+		throw?: boolean;
 	}
 
 	namespace Password {

package/docs/bundler/executables.md

@@ -279,6 +279,19 @@ $ bun build --compile --asset-naming="[name].[ext]" ./index.ts
 
 To trim down the size of the executable a little, pass `--minify` to `bun build --compile`. This uses Bun's minifier to reduce the code size. Overall though, Bun's binary is still way too big and we need to make it smaller.
 
+## Windows-specific flags
+
+When compiling a standalone executable on Windows, there are two platform-specific options that can be used to customize metadata on the generated `.exe` file:
+
+- `--windows-icon=path/to/icon.ico` to customize the executable file icon.
+- `--windows-hide-console` to disable the background terminal, which can be used for applications that do not need a TTY.
+
+{% callout %}
+
+These flags currently cannot be used when cross-compiling because they depend on Windows APIs.
+
+{% /callout %}
+
 ## Unsupported CLI arguments
 
 Currently, the `--compile` flag can only accept a single entrypoint at a time and does not support the following flags:

package/docs/bundler/index.md

@@ -1259,7 +1259,7 @@ $ bun build ./index.tsx --outdir ./out --drop=console --drop=debugger --drop=any
 
 ### `experimentalCss`
 
-Whether to enable _experimental_ support for bundling CSS files. Defaults to `false`.
+Whether to enable _experimental_ support for bundling CSS files. Defaults to `false`. In 1.2, this property will be deleted, and CSS bundling will always be enabled.
 
 This supports bundling CSS files imported from JS, as well as CSS entrypoints.
 
@@ -1275,6 +1275,12 @@ const result = await Bun.build({
 
 {% /codetabs %}
 
+### `throw`
+
+If set to `true`, `Bun.build` will throw on build failure. See the section ["Logs and Errors"](#logs-and-errors) for more details on the error message structure.
+
+In 1.2, this will default to `true`, with the previous behavior as `throw: false`
+
 ## Outputs
 
 The `Bun.build` function returns a `Promise<BuildOutput>`, defined as:
@@ -1414,7 +1420,70 @@ Refer to [Bundler > Executables](https://bun.sh/docs/bundler/executables) for co
 
 ## Logs and errors
 
-`Bun.build` only throws if invalid options are provided. Read the `success` property to determine if the build was successful; the `logs` property will contain additional details.
+<!-- 1.2 documentation -->
+<!-- On failure, `Bun.build` returns a rejected promise with an `AggregateError`. This can be logged to the console for pretty printing of the error list, or programmatically read with a `try`/`catch` block.
+
+```ts
+try {
+  const result = await Bun.build({
+    entrypoints: ["./index.tsx"],
+    outdir: "./out",
+  });
+} catch (e) {
+  // TypeScript does not allow annotations on the catch clause
+  const error = e as AggregateError;
+  console.error("Build Failed");
+
+  // Example: Using the built-in formatter
+  console.error(error);
+
+  // Example: Serializing the failure as a JSON string.
+  console.error(JSON.stringify(error, null, 2));
+}
+```
+
+{% callout %}
+
+Most of the time, an explicit `try`/`catch` is not needed, as Bun will neatly print uncaught exceptions. It is enough to just use a top-level `await` on the `Bun.build` call.
+
+{% /callout %}
+
+Each item in `error.errors` is an instance of `BuildMessage` or `ResolveMessage` (subclasses of Error), containing detailed information for each error.
+
+```ts
+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;
+}
+```
+
+On build success, the returned object contains a `logs` property, which contains bundler warnings and info messages.
+
+```ts
+const result = await Bun.build({
+  entrypoints: ["./index.tsx"],
+  outdir: "./out",
+});
+
+if (result.logs.length > 0) {
+  console.warn("Build succeeded with warnings:");
+  for (const message of result.logs) {
+    // Bun will pretty print the message object
+    console.warn(message);
+  }
+}
+``` -->
+
+By default, `Bun.build` only throws if invalid options are provided. Read the `success` property to determine if the build was successful; the `logs` property will contain additional details.
 
 ```ts
 const result = await Bun.build({
@@ -1457,6 +1526,27 @@ if (!result.success) {
 }
 ```
 
+In Bun 1.2, throwing an aggregate error like this will become the default beahavior. You can opt-into it early using the `throw: true` option.
+
+```ts
+try {
+  const result = await Bun.build({
+    entrypoints: ["./index.tsx"],
+    outdir: "./out",
+  });
+} catch (e) {
+  // TypeScript does not allow annotations on the catch clause
+  const error = e as AggregateError;
+  console.error("Build Failed");
+
+  // Example: Using the built-in formatter
+  console.error(error);
+
+  // Example: Serializing the failure as a JSON string.
+  console.error(JSON.stringify(error, null, 2));
+}
+```
+
 ## Reference
 
 ```ts
@@ -1478,39 +1568,23 @@ interface BuildConfig {
    *
    * @default "esm"
    */
-  format?: /**
-
-     * ECMAScript Module format
-     */
-  | "esm"
-    /**
-     * CommonJS format
-     * **Experimental**
-     */
-    | "cjs"
-    /**
-     * IIFE format
-     * **Experimental**
-     */
-    | "iife";
+  format?: "esm" | "cjs" | "iife";
   naming?:
     | string
     | {
         chunk?: string;
         entry?: string;
         asset?: string;
-      }; // | string;
+      };
   root?: string; // project root
   splitting?: boolean; // default true, enable code splitting
   plugins?: BunPlugin[];
-  // manifest?: boolean; // whether to return manifest
   external?: string[];
   packages?: "bundle" | "external";
   publicPath?: string;
   define?: Record<string, string>;
-  // origin?: string; // e.g. http://mydomain.com
   loader?: { [k in string]: Loader };
-  sourcemap?: "none" | "linked" | "inline" | "external" | "linked"; // default: "none", true -> "inline"
+  sourcemap?: "none" | "linked" | "inline" | "external" | "linked" | boolean; // default: "none", true -> "inline"
   /**
    * package.json `exports` conditions used when resolving imports
    *
@@ -1519,6 +1593,18 @@ interface BuildConfig {
    * https://nodejs.org/api/packages.html#exports
    */
   conditions?: Array<string> | string;
+
+  /**
+   * Controls how environment variables are handled during bundling.
+   *
+   * Can be one of:
+   * - `"inline"`: Injects environment variables into the bundled output by converting `process.env.FOO`
+   *   references to string literals containing the actual environment variable values
+   * - `"disable"`: Disables environment variable injection entirely
+   * - A string ending in `*`: Inlines environment variables that match the given prefix.
+   *   For example, `"MY_PUBLIC_*"` will only include env vars starting with "MY_PUBLIC_"
+   */
+  env?: "inline" | "disable" | `${string}*`;
   minify?:
     | boolean
     | {
@@ -1536,20 +1622,6 @@ interface BuildConfig {
    * Force emitting @__PURE__ annotations even if minify.whitespace is true.
    */
   emitDCEAnnotations?: boolean;
-  // treeshaking?: boolean;
-
-  // jsx?:
-  //   | "automatic"
-  //   | "classic"
-  //   | /* later: "preserve" */ {
-  //       runtime?: "automatic" | "classic"; // later: "preserve"
-  //       /** Only works when runtime=classic */
-  //       factory?: string; // default: "React.createElement"
-  //       /** Only works when runtime=classic */
-  //       fragment?: string; // default: "React.Fragment"
-  //       /** Only works when runtime=automatic */
-  //       importSource?: string; // default: "react"
-  //     };
 
   /**
    * Generate bytecode for the output. This can dramatically improve cold
@@ -1562,6 +1634,37 @@ interface BuildConfig {
    * @default false
    */
   bytecode?: boolean;
+  /**
+   * Add a banner to the bundled code such as "use client";
+   */
+  banner?: string;
+  /**
+   * Add a footer to the bundled code such as a comment block like
+   *
+   * `// made with bun!`
+   */
+  footer?: string;
+
+  /**
+   * **Experimental**
+   *
+   * Enable CSS support.
+   */
+  experimentalCss?: boolean;
+
+  /**
+   * Drop function calls to matching property accesses.
+   */
+  drop?: string[];
+
+  /**
+   * When set to `true`, the returned promise rejects with an AggregateError when a build failure happens.
+   * When set to `false`, the `success` property of the returned object will be `false` when a build failure happens.
+   *
+   * This defaults to `false` in Bun 1.1 and will change to `true` in Bun 1.2
+   * as most usage of `Bun.build` forgets to check for errors.
+   */
+  throw?: boolean;
 }
 
 interface BuildOutput {
@@ -1619,32 +1722,3 @@ declare class ResolveMessage {
   toString(): string;
 }
 ```
-
-<!--
-interface BuildManifest {
-  inputs: {
-    [path: string]: {
-      output: {
-        path: string;
-      };
-      imports: {
-        path: string;
-        kind: ImportKind;
-        external?: boolean;
-        asset?: boolean; // whether the import defaulted to "file" loader
-      }[];
-    };
-  };
-  outputs: {
-    [path: string]: {
-      type: "chunk" | "entrypoint" | "asset";
-      inputs: { path: string }[];
-      imports: {
-        path: string;
-        kind: ImportKind;
-        external?: boolean;
-      }[];
-      exports: string[];
-    };
-  };
-} -->

package/docs/bundler/plugins.md

@@ -58,7 +58,7 @@ const myPlugin: BunPlugin = {
 This plugin can be passed into the `plugins` array when calling `Bun.build`.
 
 ```ts
-Bun.build({
+await Bun.build({
   entrypoints: ["./app.ts"],
   outdir: "./out",
   plugins: [myPlugin],

package/docs/bundler/vs-esbuild.md

@@ -695,7 +695,7 @@ In Bun's CLI, simple boolean flags like `--minify` do not accept an argument. Ot
 - In Bun, `minify` can be a boolean or an object.
 
   ```ts
-  Bun.build({
+  await Bun.build({
     entrypoints: ['./index.tsx'],
     // enable all minification
     minify: true

package/docs/cli/bun-install.md

@@ -57,12 +57,15 @@ frozenLockfile = false
 dryRun = true
 
 # Install optionalDependencies (default: true)
+# Setting this to false is equivalent to the `--omit=optional` CLI argument
 optional = true
 
 # Install local devDependencies (default: true)
+# Setting this to false is equivalent to the `--omit=dev` CLI argument
 dev = true
 
 # Install peerDependencies (default: true)
+# Setting this to false is equivalent to the `--omit=peer` CLI argument
 peer = true
 
 # Max number of concurrent lifecycle scripts (default: (cpu count or GOMAXPROCS) x2)

package/docs/cli/install.md

@@ -130,6 +130,20 @@ $ bun install --frozen-lockfile
 
 For more information on Bun's binary lockfile `bun.lockb`, refer to [Package manager > Lockfile](https://bun.sh/docs/install/lockfile).
 
+## Omitting dependencies
+
+To omit dev, peer, or optional dependencies use the `--omit` flag.
+
+```bash
+# Exclude "devDependencies" from the installation. This will apply to the
+# root package and workspaces if they exist. Transitive dependencies will
+# not have "devDependencies".
+$ bun install --omit dev
+
+# Install only dependencies from "dependencies"
+$ bun install --omit=dev --omit=peer --omit=optional
+```
+
 ## Dry run
 
 To perform a dry run (i.e. don't actually install anything):

package/docs/guides/install/registry-scope.md

@@ -2,7 +2,9 @@
 name: Configure a private registry for an organization scope with bun install
 ---
 
-Bun does not read `.npmrc` files; instead private registries are configured via `bunfig.toml`. To configure a registry for a particular npm scope:
+Private registries can be configured using either [`.npmrc`](https://bun.sh/docs/install/npmrc) or [`bunfig.toml`](https://bun.sh/docs/runtime/bunfig#install-registry). While both are supported, we recommend using **bunfig.toml** for enhanced flexibility and Bun-specific options.
+
+To configure a registry for a particular npm scope:
 
 ```toml#bunfig.toml
 [install.scopes]

package/docs/guides/test/svelte-test.md

@@ -0,0 +1,120 @@
+---
+name: "import, require, and test Svelte components with bun test"
+---
+
+Bun's [Plugin API](/docs/runtime/plugins) lets you add custom loaders to your project. The `test.preload` option in `bunfig.toml` lets you configure your loader to start before your tests run.
+
+Firstly, install `@testing-library/svelte`, `svelte`, and `@happy-dom/global-registrator`.
+
+```bash
+$ bun add @testing-library/svelte svelte@4 @happy-dom/global-registrator
+```
+
+Then, save this plugin in your project.
+
+```ts#svelte-loader.js
+import { plugin } from "bun";
+import { compile } from "svelte/compiler";
+import { readFileSync } from "fs";
+import { beforeEach, afterEach } from "bun:test";
+import { GlobalRegistrator } from "@happy-dom/global-registrator";
+
+beforeEach(async () => {
+  await GlobalRegistrator.register();
+});
+
+afterEach(async () => {
+  await GlobalRegistrator.unregister();
+});
+
+plugin({
+  name: "svelte loader",
+  setup(builder) {
+    builder.onLoad({ filter: /\.svelte(\?[^.]+)?$/ }, ({ path }) => {
+      try {
+        const source = readFileSync(
+          path.substring(
+            0,
+            path.includes("?") ? path.indexOf("?") : path.length
+          ),
+          "utf-8"
+        );
+
+        const result = compile(source, {
+          filename: path,
+          generate: "client",
+          dev: false,
+        });
+
+        return {
+          contents: result.js.code,
+          loader: "js",
+        };
+      } catch (err) {
+        throw new Error(`Failed to compile Svelte component: ${err.message}`);
+      }
+    });
+  },
+});
+
+```
+
+---
+
+Add this to `bunfig.toml` to tell Bun to preload the plugin, so it loads before your tests run.
+
+```toml#bunfig.toml
+[test]
+# Tell Bun to load this plugin before your tests run
+preload = ["./svelte-loader.js"]
+
+# This also works:
+# test.preload = ["./svelte-loader.js"]
+```
+
+---
+
+Add an example `.svelte` file in your project.
+
+```html#Counter.svelte
+<script>
+  export let initialCount = 0;
+  let count = initialCount;
+</script>
+
+<button on:click={() => (count += 1)}>+1</button>
+```
+
+---
+
+Now you can `import` or `require` `*.svelte` files in your tests, and it will load the Svelte component as a JavaScript module.
+
+```ts#hello-svelte.test.ts
+import { test, expect } from "bun:test";
+import { render, fireEvent } from "@testing-library/svelte";
+import Counter from "./Counter.svelte";
+
+test("Counter increments when clicked", async () => {
+  const { getByText, component } = render(Counter);
+  const button = getByText("+1");
+
+  // Initial state
+  expect(component.$$.ctx[0]).toBe(0); // initialCount is the first prop
+
+  // Click the increment button
+  await fireEvent.click(button);
+
+  // Check the new state
+  expect(component.$$.ctx[0]).toBe(1);
+});
+```
+
+---
+
+Use `bun test` to run your tests.
+
+```bash
+$ bun test
+```
+
+---

package/docs/install/index.md

@@ -55,6 +55,13 @@ To install dependencies without allowing changes to lockfile (useful on CI):
 $ bun install --frozen-lockfile
 ```
 
+To exclude dependency types from installing, use `--omit` with `dev`, `optional`, or `peer`:
+
+```bash
+# Disable devDependencies and optionalDependencies
+$ bun install --omit=dev --omit=optional
+```
+
 To perform a dry run (i.e. don't actually install anything):
 
 ```bash

package/docs/install/npmrc.md

@@ -6,7 +6,7 @@ Bun supports loading configuration options from [`.npmrc`](https://docs.npmjs.co
 
 {% /callout %}
 
-# Supported options
+## Supported options
 
 ### `registry`: Set the default registry
 

package/docs/runtime/modules.md

@@ -259,6 +259,7 @@ await Bun.build({
   conditions: ["react-server"],
   target: "bun",
   entryPoints: ["./app/foo/route.js"],
+  throw: true,
 });
 ```
 

package/docs/runtime/plugins.md

@@ -307,7 +307,7 @@ await import("my-object-virtual-module"); // { baz: "quix" }
 Plugins can read and write to the [build config](https://bun.sh/docs/bundler#api) with `build.config`.
 
 ```ts
-Bun.build({
+await Bun.build({
   entrypoints: ["./app.ts"],
   outdir: "./dist",
   sourcemap: "external",
@@ -324,6 +324,7 @@ Bun.build({
       },
     },
   ],
+  throw: true,
 });
 ```
 
@@ -332,7 +333,7 @@ Bun.build({
 **NOTE**: Plugin lifcycle callbacks (`onStart()`, `onResolve()`, etc.) do not have the ability to modify the `build.config` object in the `setup()` function. If you want to mutate `build.config`, you must do so directly in the `setup()` function:
 
 ```ts
-Bun.build({
+await Bun.build({
   entrypoints: ["./app.ts"],
   outdir: "./dist",
   sourcemap: "external",
@@ -350,6 +351,7 @@ Bun.build({
       },
     },
   ],
+  throw: true,
 });
 ```
 

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "1.1.40",
+	"version": "1.1.41-canary.20241220T140556",
 	"name": "bun-types",
 	"license": "MIT",
 	"main": "",