auto-install

45 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Auto-install activation conditions

Bun activates its auto-install module resolution algorithm when no `node_modules` directory is found in the working directory or any parent directory. At that point, Bun abandons Node.js-style module resolution and uses Bun module resolution instead.

Auto-install caches to global module cache

When Bun auto-installs packages, it caches them into the global module cache, which is the same cache used by `bun install`. Packages are installed on the fly during script execution.

Auto-install version resolution priority

Bun determines which version to install using this priority order: (1) Check for a `bun.lock` file in the project root and use the version specified if it exists. (2) Scan up the tree for a `package.json` that includes the package as a dependency and use the specified semver version or range if found. (3) Otherwise, use `latest`.

Auto-install cache behavior for latest tag

When resolving `latest`, Bun checks if `package@latest` was downloaded and cached in the last 24 hours. If so, it uses the cached version. Otherwise, it downloads and installs the appropriate version from the npm registry. For other version specifiers, Bun first checks if a compatible version exists in the module cache before downloading.

Auto-install cache directory structure

Bun installs and caches packages into `<cache>/<pkg>@<version>`, allowing multiple versions of the same package to be cached simultaneously. It also creates a symlink under `<cache>/<pkg>/<version>` to speed up lookups of all cached versions of a package.

Import statement version specifiers in auto-install

To bypass version resolution, specify a version or version range directly in import statements. Supported formats include specific versions like `zod@3.0.0`, npm tags like `zod@next`, and semver ranges like `zod@^3.20.0`.

Auto-install example with version specifier

Example showing different import formats: `import { z } from "zod@3.0.0";` for a specific version, `import { z } from "zod@next";` for an npm tag, and `import { z } from "zod@^3.20.0";` for a semver range.

Auto-install basic example

Example showing basic auto-install: `import { foo } from "foo"; foo();` On the first run, Bun auto-installs `foo` at the latest version and caches it. Later runs use the cached version.

Auto-install limitation: no Intellisense

Auto-install does not provide Intellisense or TypeScript auto-completion in IDEs, as these features rely on type declaration files inside `node_modules`. Bun is investigating solutions to this limitation.

Auto-install limitation: no patch-package support

Bun's auto-install feature does not support patch-package for applying patches to dependencies.

Auto-install differs from pnpm

Unlike pnpm, which requires running `pnpm install` to create a `node_modules` folder of symlinks, Bun resolves dependencies on the fly when running a file without needing any `install` command. Bun also does not create a `node_modules` folder.

Auto-install differs from Yarn Plug'N'Play

Unlike Yarn Plug'N'Play, which requires running `yarn install` before executing a script, Bun resolves dependencies on the fly when running a file. Additionally, Yarn's use of zip files for storing dependencies makes dependency loading slower at runtime due to slower random access reads compared to disk lookups, whereas Bun uses direct disk storage.

Auto-install differs from Deno

Unlike Deno, which requires an `npm:` specifier before each npm import, lacks support for import maps through `compilerOptions.paths` in `tsconfig.json`, and has incomplete support for `package.json` settings, Bun supports standard npm imports with full `tsconfig.json` import map support. However, Bun does not currently support URL imports like Deno does.

Auto-install space efficiency benefit

Each version of a dependency exists in only one place on disk in Bun's auto-install system, saving space and time compared to redundant per-project installations found in traditional Node.js package managers.

Auto-install portability benefit

Bun auto-install makes source files self-contained. Scripts and gists can be shared without zipping up a directory of code and config files. With version specifiers in import statements, not even a `package.json` is necessary.

Auto-install convenience benefit

With Bun's auto-install, there is no need to run `npm install` or `bun install` before running a file or script with `bun run`.

Auto-install backwards compatibility with package.json

Bun still respects versions specified in `package.json` if one exists, enabling users to switch to Bun-style resolution with a single command: `rm -rf node_modules`.

bunfig.toml install.optional setting

In the [install] section, optional is a boolean that controls whether to install optional dependencies. Default is true.

bunfig.toml install.dev setting

In the [install] section, dev is a boolean that controls whether to install development dependencies. Default is true.

bunfig.toml install.peer setting

In the [install] section, peer is a boolean that controls whether to install peer dependencies. Default is true.

bunfig.toml install.production setting

In the [install] section, production is a boolean that controls whether bun install runs in production mode. Default is false. In production mode, devDependencies are not installed. The --production CLI flag overrides this.

bunfig.toml install.exact setting

In the [install] section, exact is a boolean that controls whether to set an exact version in package.json. Default is false. By default Bun uses caret ranges; if the latest version is 2.4.1, Bun writes ^2.4.1 which accepts any version from 2.4.1 up to (but not including) 3.0.0.

bunfig.toml install.ignoreScripts setting

In the [install] section, ignoreScripts is a boolean that controls whether to skip lifecycle scripts during install. Default is false. When true, Bun does not run any preinstall, install, postinstall, or prepare scripts for the project or packages in trustedDependencies. Equivalent to the --ignore-scripts flag.

bunfig.toml install.concurrentScripts setting

In the [install] section, concurrentScripts is the maximum number of concurrent lifecycle scripts to run at once. Defaults to two times the number of CPU cores. Equivalent to the --concurrent-scripts flag.

bunfig.toml install.saveTextLockfile setting

In the [install] section, saveTextLockfile controls whether bun install generates a binary bun.lockb or a text-based bun.lock file when no lockfile is present. Default is true (since Bun v1.2).

bunfig.toml install.auto setting values

In the [install] section, auto configures Bun's auto-install behavior. Default is "auto". Valid values: "auto" (resolve from local node_modules if exists, otherwise auto-install), "force" (always auto-install even if node_modules exists), "disable" (never auto-install), "fallback" (check local node_modules first, then auto-install packages not found; equivalent to bun -i).

bunfig.toml install.prefer setting values

In the [install] section, prefer configures how Bun resolves package versions against npm registry when running scripts. Default is "online". Valid values: "online" (check registry for stale packages as needed), "offline" (skip staleness checks, resolve from local cache; equivalent to --prefer-offline), "latest" (always check npm for latest matching versions; equivalent to --prefer-latest).

bunfig.toml install.frozenLockfile setting

In the [install] section, frozenLockfile is a boolean that when true, prevents bun install from updating bun.lock. Default is false. If package.json and existing bun.lock disagree, the install errors.

bunfig.toml install.dryRun setting

In the [install] section, dryRun is a boolean that controls whether bun install actually installs dependencies. Default is false. When true, it's equivalent to passing --dry-run to all bun install commands.

bunfig.toml install.globalBinDir setting

In the [install] section, globalBinDir specifies the directory where Bun links the binaries of globally installed packages. Can also be set with BUN_INSTALL_BIN environment variable. Example: globalBinDir = "~/.bun/bin".

bunfig.toml install.registry setting formats

In the [install] section, registry can be set in three ways: as a string URL (default is https://registry.npmjs.org/), as an object with url and token (registry = { url = "https://registry.npmjs.org", token = "123456" }), or as a URL with embedded credentials (registry = "https://username:password@registry.npmjs.org").

bunfig.toml install.linkWorkspacePackages setting

In the [install] section, linkWorkspacePackages is a boolean that controls whether to link workspace packages from the monorepo root to their respective node_modules directories. Default is true.

bunfig.toml install.scopes setting

In the [install.scopes] section, configure a registry for a particular scope (e.g., @myorg/<package>). Can be a string URL, an object with username/password and url (supporting environment variable references like $npm_password), or an object with token and url. Example: [install.scopes] myorg = { token = "$npm_token", url = "https://registry.myorg.com/" }.

bunfig.toml install.ca and install.cafile settings

In the [install] section, configure a CA certificate by setting ca to the certificate string or cafile to the path of a certificate file. The file can contain multiple certificates.

bunfig.toml install.cache settings

In the [install.cache] section, configure cache behavior: dir specifies the directory to use (example: "~/.bun/install/cache"), disable when true prevents loading from the global cache (Bun may still write to node_modules/.cache), and disableManifest when true always resolves latest versions from registry.

bunfig.toml install.lockfile settings

In the [install.lockfile] section, save controls whether to generate a lockfile on bun install (default true), and print generates a non-Bun lockfile alongside bun.lock (bun.lock is always created). Only "yarn" is supported for print value.

bunfig.toml install.linker setting values

In the [install] section, linker configures the linker strategy for how bun install lays out dependencies in node_modules. Defaults to "isolated" for new workspaces and "hoisted" for new single-package projects and existing projects. Valid values: "hoisted" (link dependencies in shared node_modules), "isolated" (link dependencies inside each package installation).

bunfig.toml install.globalStore setting

In the [install] section, globalStore is a boolean that when using the "isolated" linker, shares package installations across projects in a global virtual store at <cache>/links/ and links node_modules/.bun/<pkg>@<ver> into it. Makes warm installs after rm -rf node_modules much faster. Default is false. Can also be set with BUN_INSTALL_GLOBAL_STORE environment variable.

bunfig.toml install.publicHoistPattern setting

In the [install] section, publicHoistPattern is an array of glob patterns. When using the "isolated" linker, packages matching these patterns are hoisted to the root node_modules directory so they can be resolved by any package in the project. Default is []. Example: publicHoistPattern = ["*eslint*", "*prettier*"].

bunfig.toml install.hoistPattern setting

In the [install] section, hoistPattern is an array of glob patterns. When using the "isolated" linker, packages matching these patterns are hoisted to a fallback directory inside the virtual store (node_modules/.bun/node_modules) so they can be resolved by other packages in the virtual store. By default every package is hoisted there, equivalent to ["*"].

bunfig.toml install.hoist setting

In the [install] section, hoist is a boolean that applies only to the "isolated" linker. When true (default), Bun creates node_modules/.bun/node_modules, a fallback directory containing symlinks to every installed package (or only packages matching hoistPattern if set). This sits on the upward resolution path so packages can resolve undeclared dependencies. Set to false to skip creating this directory; then undeclared imports from store packages fail unless linked at project root node_modules. Default is true.

bunfig.toml install.logLevel setting

In the [install] section, logLevel sets the log level for bun install. Valid values: "debug", "warn", "error".

bunfig.toml install.security.scanner setting

In the [install.security] section, scanner specifies a security scanner package to scan dependencies for vulnerabilities before installation. Example: scanner = "@oven/bun-security-scanner". When configured, auto-install is disabled for security, packages are scanned before installation, installation is cancelled if fatal issues are found, and security warnings are displayed during installation.

bunfig.toml install.minimumReleaseAge setting

In the [install] section, minimumReleaseAge configures a minimum age in seconds for npm package versions. Package versions published more recently than this threshold are filtered out during installation. Default is null (disabled). Example: minimumReleaseAge = 259200 (3 days).

bunfig.toml install.minimumReleaseAgeExcludes setting

In the [install] section, minimumReleaseAgeExcludes is an array of package names exempt from the minimumReleaseAge check. Default is []. Example: minimumReleaseAgeExcludes = ["@types/bun", "typescript"].

Give your agent this brain