bun-types - npm Package Compare versions

Comparing version 1.1.40 to 1.1.41-canary.20241220T140556

docs/bundler/executables.md

@@ -282,2 +282,15 @@ Bun's bundler implements a `--compile` flag for generating a standalone binary from a TypeScript or JavaScript file.
 
+## 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
@@ -284,0 +297,0 @@

docs/bundler/index.md

@@ -1262,3 +1262,3 @@ Bun's fast native bundler is now in beta. It can be used via the `bun build` CLI command or the `Bun.build()` JavaScript API.
 
-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.
 
@@ -1279,2 +1279,8 @@ This supports bundling CSS files imported from JS, as well as CSS entrypoints.
 
+### `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
@@ -1419,5 +1425,51 @@
 
-`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({
@@ -1428,2 +1480,19 @@ entrypoints: ["./index.tsx"],
 
+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({
+  entrypoints: ["./index.tsx"],
+  outdir: "./out",
+});
+
 if (!result.success) {
@@ -1464,2 +1533,23 @@ console.error("Build failed");
 
+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
@@ -1486,17 +1576,3 @@
    */
-  format?: /**
-
-     * ECMAScript Module format
-     */
-  | "esm"
-    /**
-     * CommonJS format
-     * **Experimental**
-     */
-    | "cjs"
-    /**
-     * IIFE format
-     * **Experimental**
-     */
-    | "iife";
+  format?: "esm" | "cjs" | "iife";
   naming?:
@@ -1508,7 +1584,6 @@ | 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[];
@@ -1518,5 +1593,4 @@ packages?: "bundle" | "external";
   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"
   /**
@@ -1530,2 +1604,14 @@ * package.json `exports` conditions used when resolving imports
   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?:
@@ -1548,17 +1634,3 @@ | boolean
   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"
-  //     };
-
   /**
@@ -1575,2 +1647,33 @@ * Generate bytecode for the output. This can dramatically improve cold
   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;
 }
@@ -1633,30 +1736,1 @@
 ```
-
-<!--
-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[];
-    };
-  };
-} -->

docs/bundler/plugins.md

@@ -61,3 +61,3 @@ Bun provides a universal plugin API that can be used to extend both the _runtime_ and _bundler_.
 ```ts
-Bun.build({
+await Bun.build({
   entrypoints: ["./app.ts"],
@@ -64,0 +64,0 @@ outdir: "./out",

docs/bundler/vs-esbuild.md

@@ -698,3 +698,3 @@ Bun's bundler API is inspired heavily by [esbuild](https://esbuild.github.io/). Migrating to Bun's bundler from esbuild should be relatively painless. This guide will briefly explain why you might consider migrating to Bun's bundler and provide a side-by-side API comparison reference for those who are already familiar with esbuild's API.
   ```ts
-  Bun.build({
+  await Bun.build({
     entrypoints: ['./index.tsx'],
@@ -701,0 +701,0 @@ // enable all minification

docs/cli/bun-install.md

@@ -60,8 +60,11 @@ ### `bun install`
 # 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
@@ -68,0 +71,0 @@

docs/cli/install.md

@@ -133,2 +133,16 @@ The `bun` CLI contains a Node.js-compatible package manager designed to be a dramatically faster replacement for `npm`, `yarn`, and `pnpm`. It's a standalone tool that will work in pre-existing Node.js projects; if your project has a `package.json`, `bun install` can help you speed up your workflow.
 
+## 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
@@ -135,0 +149,0 @@

docs/guides/install/registry-scope.md

@@ -5,4 +5,6 @@ ---
 
-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
@@ -9,0 +11,0 @@ [install.scopes]

docs/install/index.md

@@ -58,2 +58,9 @@ The `bun` CLI contains an `npm`-compatible package manager designed to be a faster replacement for existing package management tools like `npm`, `yarn`, and `pnpm`. It's designed for Node.js compatibility; use it in any Bun or Node.js project.
 
+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):
@@ -60,0 +67,0 @@

docs/install/npmrc.md

@@ -9,3 +9,3 @@ Bun supports loading configuration options from [`.npmrc`](https://docs.npmjs.com/cli/v10/configuring-npm/npmrc) files, allowing you to reuse existing registry/scope configurations.
 
-# Supported options
+## Supported options
 
@@ -12,0 +12,0 @@ ### `registry`: Set the default registry

docs/runtime/modules.md

@@ -262,2 +262,3 @@ Module resolution in JavaScript is a complex topic.
   entryPoints: ["./app/foo/route.js"],
+  throw: true,
 });
@@ -264,0 +265,0 @@ ```

docs/runtime/plugins.md

@@ -310,3 +310,3 @@ Bun provides a universal plugin API that can be used to extend both the _runtime_ and [_bundler_](https://bun.sh/docs/bundler).
 ```ts
-Bun.build({
+await Bun.build({
   entrypoints: ["./app.ts"],
@@ -328,2 +328,3 @@ outdir: "./dist",
   ],
+  throw: true,
 });
@@ -337,3 +338,3 @@ ```
 ```ts
-Bun.build({
+await Bun.build({
   entrypoints: ["./app.ts"],
@@ -356,2 +357,3 @@ outdir: "./dist",
   ],
+  throw: true,
 });
@@ -358,0 +360,0 @@ ```

package.json

 {
-	"version": "1.1.40",
+	"version": "1.1.41-canary.20241220T140556",
 	"name": "bun-types",
@@ -4,0 +4,0 @@ "license": "MIT",

New alerts

No v1

Quality

Package is not semver >=1. This means it is not stable and does not support ^ ranges.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

1240575

0.61%

Number of package files

288

0.35%

Lines of code

12617

0.06%

Worsened metrics

Number of low quality alerts

1

Infinity%

No dependency changes