mirror of
https://github.com/oven-sh/bun
synced 2026-02-02 15:08:46 +00:00
7dcd49f832
## Summary - The default trusted dependencies list should only apply to packages installed from npm - Non-npm sources (file:, link:, git:, github:) now require explicit trustedDependencies - This prevents malicious packages from spoofing trusted names through local paths or git repos ## Test plan - [x] Added test: file: dependency named "esbuild" does NOT auto-run postinstall scripts - [x] Added test: file: dependency runs scripts when explicitly added to trustedDependencies - [x] Verified tests fail with system bun (old behavior) and pass with new build - [x] Build compiles successfully 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Bot <claude-bot@bun.sh> Co-authored-by: Claude <noreply@anthropic.com> Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com> Co-authored-by: Jarred Sumner <jarred@jarredsumner.com> Co-authored-by: Dylan Conway <dylan.conway567@gmail.com>
65 lines
2.7 KiB
Plaintext
65 lines
2.7 KiB
Plaintext
---
|
|
title: "Lifecycle scripts"
|
|
description: "How Bun handles package lifecycle scripts securely"
|
|
---
|
|
|
|
Packages on `npm` can define _lifecycle scripts_ in their `package.json`. Some of the most common are below, but there are [many others](https://docs.npmjs.com/cli/v10/using-npm/scripts).
|
|
|
|
- `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 read and execute at the appropriate time. But executing arbitrary scripts represents a potential security risk, so—unlike other `npm` clients—Bun does not execute arbitrary lifecycle scripts by default.
|
|
|
|
---
|
|
|
|
## `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](https://nodejs.org/api/addons.html). For example, `node-sass` is a popular package that uses `postinstall` to build a native binary for Sass.
|
|
|
|
```json package.json icon="file-json"
|
|
{
|
|
"name": "my-app",
|
|
"version": "1.0.0",
|
|
"dependencies": {
|
|
"node-sass": "^6.0.1"
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## `trustedDependencies`
|
|
|
|
Instead of executing arbitrary scripts, Bun uses a "default-secure" approach. You can add certain packages to an allow list, and Bun will execute lifecycle scripts for those packages. To tell Bun to allow lifecycle scripts for a particular package, add the package name to `trustedDependencies` array in your `package.json`.
|
|
|
|
```json package.json icon="file-json"
|
|
{
|
|
"name": "my-app",
|
|
"version": "1.0.0",
|
|
"trustedDependencies": ["node-sass"] // [!code ++]
|
|
}
|
|
```
|
|
|
|
Once added to `trustedDependencies`, install/re-install the package. Bun will read this field and run lifecycle scripts for `my-trusted-package`.
|
|
|
|
The top 500 npm packages with lifecycle scripts are allowed by default. You can see the full list [here](https://github.com/oven-sh/bun/blob/main/src/install/default-trusted-dependencies.txt).
|
|
|
|
<Note>
|
|
The default trusted dependencies list only applies to packages installed from npm. For packages from other sources
|
|
(such as `file:`, `link:`, `git:`, or `github:` dependencies), you must explicitly add them to `trustedDependencies`
|
|
to run their lifecycle scripts, even if the package name matches an entry in the default list. This prevents malicious
|
|
packages from spoofing trusted package names through local file paths or git repositories.
|
|
</Note>
|
|
|
|
---
|
|
|
|
## `--ignore-scripts`
|
|
|
|
To disable lifecycle scripts for all packages, use the `--ignore-scripts` flag.
|
|
|
|
```bash terminal icon="terminal"
|
|
bun install --ignore-scripts
|
|
```
|