Lifecycle scripts - Bun

Lifecycle scripts - BunDocumentation Index

Fetch the complete documentation index at: /docs/llms.txt

Use this file to discover all available pages before exploring further.

Skip to main contentBun home pageSearch...⌘KInstall BunSearch...NavigationAdvanced ConfigurationLifecycle scriptsRuntimePackage ManagerBundlerTest RunnerGuidesReferenceBlogFeedback:first-child]:!hidden peer-[.is-custom]:[&>:first-child]:sm:!hidden peer-[.is-custom]:[&>:first-child]:md:!hidden peer-[.is-custom]:[&>:first-child]:lg:!hidden peer-[.is-custom]:[&>:first-child]:xl:!hidden">Core Commandsbun installbun addbun removebun updatebunxPublishing & Analysisbun publishbun outdatedbun whybun auditbun infoWorkspace ManagementWorkspacesCatalogsbun linkbun pmAdvanced Configurationbun patchbun --filterGlobal cacheGlobal virtual storeIsolated installsLockfileLifecycle scriptsScopes and registriesOverrides and resolutionsSecurity Scanner API.npmrc supportOn this pagepostinstalltrustedDependenciesBehavior of the trustedDependencies field--ignore-scriptsAdvanced ConfigurationLifecycle scriptsCopy pagespan]:line-clamp-1 overflow-hidden group flex items-center py-0.5 gap-1 text-sm text-gray-950/50 dark:text-white/50 group-hover:text-gray-950/70 dark:group-hover:text-white/70 rounded-none rounded-r-xl border px-3 border-gray-200 aspect-square dark:border-white/[0.07] bg-background-light dark:bg-background-dark hover:bg-gray-600/5 dark:hover:bg-gray-200/5" aria-label="More actions" type="button" id="radix-_R_n4ctdbsnlht5lebsnpfdb_" aria-haspopup="menu" aria-expanded="false" data-state="closed">*]:[overflow-wrap:anywhere]">

How Bun handles package lifecycle scripts securely

Copy pagespan]:line-clamp-1 overflow-hidden group flex items-center py-0.5 gap-1 text-sm text-gray-950/50 dark:text-white/50 group-hover:text-gray-950/70 dark:group-hover:text-white/70 rounded-none rounded-r-xl border px-3 border-gray-200 aspect-square dark:border-white/[0.07] bg-background-light dark:bg-background-dark hover:bg-gray-600/5 dark:hover:bg-gray-200/5" aria-label="More actions" type="button" id="radix-_R_1cctdbsnlht5lebsnpfdb_" aria-haspopup="menu" aria-expanded="false" data-state="closed">Packages on npm can define lifecycle scripts in their package.json. Some of the most common are below, but there are 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 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. For example, node-sass is a popular package that uses postinstall to build a native binary for Sass. package.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. package.json

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

Once added to trustedDependencies, install/re-install the package. Bun will read this field and run lifecycle scripts for my-trusted-package. A curated list of popular npm packages with lifecycle scripts is allowed by default. You can see the full list here. 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. ​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: package.jsonPackages allowed to run lifecycle scriptstrustedDependencies omittedThe packages in Bun’s built-in list (npm sources only).trustedDependencies: ["pkg-a", ...]Only the listed packages. The default list is ignored.trustedDependencies: []No packages, including none from the default list. 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) — they are no longer trusted implicitly. ​--ignore-scripts To disable lifecycle scripts for all packages, use the --ignore-scripts flag. terminal

bun install --ignore-scripts

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

[install]
ignoreScripts = true

Or in .npmrc: .npmrc

ignore-scripts=true

Was this page helpful?

YesNoSuggest editsRaise issueLockfilePreviousScopes and registriesNext⌘IxgithubdiscordyoutubePowered byThis documentation is built and hosted on Mintlify, a developer documentation platform