Lifecycle scripts

Packages on npm can define lifecycle scripts in their package.json. These are some of the most common, among many others:

• preinstall: Runs before the package is installed
• postinstall: Runs after the package is installed
• preuninstall: Runs before the package is uninstalled
• prepublishOnly: Runs before the package is published

These scripts are arbitrary shell commands that the package manager is expected to run at the appropriate time. Because running arbitrary code is a security risk, Bun does not execute arbitrary lifecycle scripts by default, unlike other npm clients.

postinstall#

The postinstall script is particularly important. It's widely used to build or install platform-specific binaries for packages that are implemented as native Node.js add-ons. For example, node-sass uses postinstall to build a native binary for Sass.

{
  "name": "my-app",
  "version": "1.0.0",
  "dependencies": {
    "node-sass": "^6.0.1"
  }
}

trustedDependencies#

Bun is "default-secure": it only runs lifecycle scripts for packages on an allow list. To allow lifecycle scripts for a particular package, add its name to the trustedDependencies array in your package.json.

{
  "name": "my-app",
  "version": "1.0.0",
  "trustedDependencies": ["node-sass"] 
}

After adding the package to trustedDependencies, run bun install. Bun reads the field, runs its lifecycle scripts and records the name in the lockfile. bun install --frozen-lockfile and bun ci run them only for packages they install, not for one that is already in node_modules. For a dependency installed under another name ("alias": "npm:node-sass@^6.0.1"), list the name of the package, not the alias.

A curated list of popular npm packages with lifecycle scripts is allowed by default. See the full list.

Behavior of the trustedDependencies field#

Defining trustedDependencies in package.json replaces the default list rather than extending it. Exactly one of three modes applies per project:

Set trustedDependencies: [] when you want to opt out of the default allow list entirely without passing --ignore-scripts on every install. If you define trustedDependencies with an explicit list, include any packages from the default list whose lifecycle scripts you still need (for example, sharp or esbuild). Bun no longer trusts those packages implicitly.

The lockfile records the list, even if it's empty. In a checkout without the workspace that declares it (a Docker layer, for example), bun install --frozen-lockfile still ignores the default list, and only the packages that the lockfile records run their scripts.

--ignore-scripts#

To disable lifecycle scripts for all packages, use the --ignore-scripts flag.

bun install --ignore-scripts

To make this the default for a project, set install.ignoreScripts in bunfig.toml:

[install]
ignoreScripts = true

Or in .npmrc:

ignore-scripts=true

Or with npm's environment variable, for example in a CI job:

NPM_CONFIG_IGNORE_SCRIPTS=true bun install

Bun reads the value like ignore-scripts=<value> in .npmrc, and ignores an empty one. The variable only turns scripts off: false and 0 do not undo a config file. Bun does not read it from .env files.

Environment variables#

Like npm, Bun sets these variables for each lifecycle script: