docs: list supported lifecycle scripts, note that npm's dependencies script is not implemented - #30249
docs: list supported lifecycle scripts, note that npm's dependencies script is not implemented#30249robobun wants to merge 1 commit into
dependencies script is not implemented#30249Conversation
WalkthroughDocumentation now enumerates the exact npm lifecycle hooks Bun supports for install/add/remove/update, publish/pack, and version commands; states which npm hooks Bun does not invoke; clarifies prepare-hook scope and root script ordering; and limits dependency lifecycle execution to trusted or workspace packages. ChangesLifecycle Scripts Documentation
🚥 Pre-merge checks | ✅ 4✅ Passed checks (4 passed)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/pm/lifecycle.mdx (1)
63-63:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winReplace the stale placeholder package name.
my-trusted-packagedoesn't match thenode-sassexample above, so this reads like copied placeholder text instead of a concrete instruction.✏️ Suggested text cleanup
-Once added to trustedDependencies, install/re-install the package. Bun will read this field and run lifecycle scripts for `my-trusted-package`. +Once added to `trustedDependencies`, reinstall the package. Bun will then run lifecycle scripts for that package.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/pm/lifecycle.mdx` at line 63, The sentence uses a stale placeholder `my-trusted-package`; update it to match the earlier example package (`node-sass`) or whichever concrete package was used above so the instruction reads consistently (e.g., change "lifecycle scripts for `my-trusted-package`" to "lifecycle scripts for `node-sass`"); locate the occurrence near the `trustedDependencies` explanation and replace the placeholder package name accordingly.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/pm/lifecycle.mdx`:
- Line 31: Update the sentence "Lifecycle scripts of installed dependencies only
run for packages listed in `trustedDependencies`" to clarify that scripts run
for packages that are either listed in `trustedDependencies` or included in
Bun's built-in npm package allowlist; mention both the explicit
trustedDependencies setting and Bun's internal allowlist so readers understand
both paths that permit dependency lifecycle scripts to run.
---
Outside diff comments:
In `@docs/pm/lifecycle.mdx`:
- Line 63: The sentence uses a stale placeholder `my-trusted-package`; update it
to match the earlier example package (`node-sass`) or whichever concrete package
was used above so the instruction reads consistently (e.g., change "lifecycle
scripts for `my-trusted-package`" to "lifecycle scripts for `node-sass`");
locate the occurrence near the `trustedDependencies` explanation and replace the
placeholder package name accordingly.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: 48baed5b-d63c-467a-9c40-61b456d98784
📒 Files selected for processing (1)
docs/pm/lifecycle.mdx
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/pm/lifecycle.mdx`:
- Line 31: Update the sentence "Lifecycle scripts of installed dependencies only
run for packages on Bun's default trusted list or in your project's
`trustedDependencies`" to also mention workspace/monorepo packages: clarify that
lifecycle scripts run for packages on Bun's default trusted list, packages
listed in `trustedDependencies`, and packages that are part of the current
workspace/monorepo (i.e., local workspace packages resolved by the installer).
Keep the mention concise and add an inline pointer to the workspace exception so
readers know workspace packages are allowed by the install logic.
- Around line 12-19: The current text implies preprepare/prepare/postprepare
always run during bun install/add/remove/update; update the wording so it
clarifies these hooks are conditional — only queued/executed for packages with
resolution types "git", "github", or "root" (i.e., non-registry resolutions) and
are not run for normal registry installs; locate the section listing the hooks
(references: preprepare, prepare, postprepare) and add a short qualifying
sentence noting the resolution-type condition and when those hooks are skipped.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: cc9d2c66-09ce-4c1a-8f75-231f3b66758b
📒 Files selected for processing (1)
docs/pm/lifecycle.mdx
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/pm/lifecycle.mdx`:
- Line 42: Update the sentence that begins "Lifecycle scripts of installed
dependencies..." to explicitly mention the `from_git` trust path so readers know
git- and github-sourced packages can also be trusted: change the wording to
state that lifecycle scripts run for packages on Bun's default trusted list,
packages declared in `trustedDependencies`, workspace packages, and packages
installed via the `from_git`/`git:`/`github:` install path; reference the
`from_git` token in the sentence so the doc matches the install logic.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: 31b0022e-88a9-45a7-a12f-0c31a16872c2
📒 Files selected for processing (1)
docs/pm/lifecycle.mdx
|
Updated 9:32 AM PT - Jun 30th, 2026
✅ @robobun, your commit 2014cc0b7047c3d666e0802bca9d730e94079e59 passed in 🧪 To try this PR locally: bunx bun-pr 30249That installs a local version of the PR into your bun-30249 --bun |
There was a problem hiding this comment.
LGTM — all prior feedback addressed; the remaining coderabbit note about a from_git trust path is a false positive (no such bypass exists in hasTrustedDependency / PackageInstaller.zig:1171), so line 42 is accurate as written.
Extended reasoning...
Overview
Docs-only change to docs/pm/lifecycle.mdx that replaces a vague "common scripts" list with a precise, source-verified enumeration of which lifecycle hooks Bun runs per command (install/add/remove/update, publish/pack, pm version), which resolution types get the prepare-family hooks, the root-script timing divergence from npm, and which npm hooks Bun never invokes. No code, config, or build changes.
Security risks
None. Pure documentation; does not alter trust gating, script execution, or any runtime behavior.
Level of scrutiny
Low-to-moderate — docs accuracy matters here since the page describes security-relevant behavior (when arbitrary scripts run), but every claim has been cross-checked against source by the author with file:line citations, and I independently re-verified the install-time script ordering (install_with_manager.zig), prepare-hook gating (Scripts.zig:159), workspace trust short-circuit (PackageInstaller.zig:1171), and hasTrustedDependency (lockfile.zig:2126-2134).
Other factors
- All three of my earlier inline comments (root
preinstalltiming, default trusted list wording,prerestart/prestopexamples) were addressed in d35dd37 / 334e260 / 634a6f1 and are resolved. - The one unresolved coderabbit comment claims git/github deps have a separate
from_gittrust path. I greppedsrc/installand readhasTrustedDependency: there is no such path — git/github deps go through the sameis_trustedgate and are excluded from the default list (which is npm-only). The existing<Note>further down the page already documents this correctly. The sentence at line 42 is accurate and should not be changed per that suggestion. - The inline 🔵 pre-existing note about the
postinstall→preinstallcopy/paste typo inScripts.zig:137is a real code bug but is unrelated to this docs PR and explicitly flagged as not blocking. docs/pm/has no CODEOWNERS entry.
…ies` script is not implemented Users following the link out to npm's scripts docs could see npm's `dependencies` hook (which runs after node_modules changes) and reasonably assume Bun runs it too. It doesn't, and neither do `preuninstall`, `postuninstall`, etc. Replace the misleading "most common" bullet list with a precise "Supported lifecycle scripts" section grouped by command: - install/add/remove/update: preinstall, install, postinstall, and preprepare/prepare/postprepare (the prepare family only runs for root, git:, github:, and workspace packages, not npm tarballs) - publish/pack: prepublishOnly, prepack, prepare, postpack, publish, postpublish - pm version: preversion, version, postversion Also note that root install-time scripts run as a single batch after node_modules is populated (a divergence from npm's preinstall timing), that generic pre<name>/post<name> wrappers still fire via bun run, and that workspace packages are always trusted. Fixes #30247
634a6f1 to
2014cc0
Compare
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
There was a problem hiding this comment.
LGTM — docs-only change, all prior feedback addressed and source-verified.
Extended reasoning...
Overview
This PR rewrites the intro of docs/pm/lifecycle.mdx to enumerate exactly which npm lifecycle scripts Bun invokes, grouped by command (install/add/remove/update, publish/pm pack, pm version), and explicitly calls out hooks Bun does not run (dependencies, preuninstall, postuninstall). It also adds a callout documenting Bun's divergence from npm on root preinstall timing. Single file touched, ~40 lines of prose changed; the rest of the page (trustedDependencies, --ignore-scripts) is preserved from main after a clean rebase.
Security risks
None. This is documentation only — no code, config, build, or test changes. The content describes existing behavior; it does not alter what scripts Bun runs or how trust is evaluated.
Level of scrutiny
Low. Docs-only, and the factual claims have been cross-checked against source (lockfile.zig, Scripts.zig, install_with_manager.zig, pack_command.zig, pm_version_command.zig, run_command.zig) during the review threads on this PR. The rebase note explains conflict resolution and the final file content correctly retains main's trustedDependencies behavior table and --ignore-scripts sections.
Other factors
Every inline thread (CodeRabbit's and my own from earlier runs) is resolved: the prepare-family resolution-type gating, workspace trust exception, default-trusted-list wording, root preinstall timing, and the prerestart/prestop examples were all corrected in follow-up commits. The one remaining flagged item (a pre-existing copy/paste bug in Scripts.zig:137) is explicitly out of scope for a docs PR and is being tracked separately. CI passed on the latest commit. No outstanding human reviewer comments. Approving.
|
I am closing this PR in favor of #41350. That PR fixes #30247 with a smaller change. One claim in this PR is wrong. The Note says: "Unlike npm, Bun runs the root project's install-time scripts as a single batch after I tested this with npm 11.16.0 and a local tarball dependency. The root The claims about Bun itself match main. The hook list matches |
This branch was successfully deployed
1 participant
What
Rewrite the top of
docs/pm/lifecycle.mdxto list exactly which lifecycle scripts Bun runs, grouped by command, and to explicitly note that npm'sdependenciesscript (and a few other npm hooks) are not invoked by Bun.Why
The docs today linked out to npm's scripts page with "there are many others." A reader could reasonably read that and assume npm's
dependenciesscript — which runs afternode_moduleschanges — would run afterbun add/bun remove. It does not.The old "most common" bullet list also presented
preuninstallandprepublishOnlyas lifecycle scripts without qualifying which commands actually invoke them, which was misleading.What now
The page now lists, by command, the exact set Bun supports:
bun install/add/remove/update:preinstall,install,postinstall, pluspreprepare/prepare/postpreparefor root,git:,github:, and (forprepare) workspace packages only (source:src/install/lockfile.zig:58,src/install/lockfile/Package/Scripts.zig:159)bun publish/bun pm pack:prepublishOnly,prepack,prepare,postpack,publish,postpublish(source:src/cli/pack_command.zig:1259)bun pm version:preversion,version,postversion(source:src/cli/pm_version_command.zig:74)It explicitly calls out that npm package-manager hooks
dependencies,preuninstall, andpostuninstallare not invoked, and notes two Bun-specific behaviors surfaced in review:node_modulesis populated (a divergence from npm'spreinstalltiming; source:src/install/PackageManager/install_with_manager.zig:935).pre<name>/post<name>wrappers still fire viabun run <name>(source:src/cli/run_command.zig:1763), so e.g.prerestartis reachable and is not listed as "not invoked."Fixes #30247
Rebase note
Rebased onto current
main, which had meanwhile restructured this file (editorial pass #33112 and the new "Behavior of thetrustedDependenciesfieldsection from #31027). Resolved by keeping all of main's content intact (thepostinstall,trustedDependencies+ behavior-table, and--ignore-scriptssections) and replacing only main's misleading intro bullet list with the new "Supported lifecycle scripts" section. The trust-summary sentence now links to main'strustedDependencies` section rather than restating the allow-list rules, so the two don't drift.