post-install documentation

[Tezra]

The esbuild package.json includes a "postinstall" script, but I can't find any documentation on it. As far as I can tell, it seems to only do async validation, so should be safe to disable.

I'm trying to setup an automated build using npm ci --ignore-scripts, which will prevent pre/postinstall scripts from running. So I was just wondering if I need to do anything if postinstall does not run?

In the future, a note in the documentation of what the postinstall script does, and what to do if you need to set ignore-scripts would be nice.

[evanw]

I can add some documentation about that. The installation flow is designed to still function with either --ignore-scripts or --no-optional (although not both, that will break). Specifically:

• npm i esbuild

  This is the default installation flow. The esbuild binary for the current platform should be automatically selected and installed from esbuild's optional dependencies by the package manager. The install script then runs which a) checks that the esbuild binary is the correct version (which is sometimes not the case due to package manager bugs) and b) optimizes the esbuild command in node_modules/.bin to be the esbuild executable itself instead of a JavaScript shim file that runs the actual esbuild executable.

• npm i esbuild --ignore-scripts

  The install script doesn't run. However, the esbuild binary for the current platform should still be automatically selected and installed from esbuild's optional dependencies by the package manager. The esbuild command in node_modules/.bin remains pointed to the JavaScript shim file that runs the actual esbuild executable. This means that running esbuild using for example ./node_modules/.bin/esbuild will experience some unnecessary performance overhead as an extra node process will be launched to invoke esbuild. Uses of the esbuild API (so not the esbuild CLI) do not have degraded performance as that use case already requires a node process to be launched (for the host code using the API). I think I remember the performance overhead of launching the extra node process to be 200ms at one point. Not the end of the world.

• npm i esbuild --no-optional

  The package manager doesn't install the esbuild binary for the current platform as it has been instructed not to. The install script then runs and notices the missing esbuild binary and attempts to download it manually from the npm registry. This is less robust than the default installation flow because many people have complex package manager configuration that esbuild's install script can't necessarily replicate. For example, this may fail if the network path to the internet involves a proxy, or a custom npm registry is in use. But this install flow has been added because it works for some people who do this.

• npm i esbuild --ignore-scripts --no-optional

  In this scenario, the installed esbuild package is broken because nothing downloads the actual esbuild binary. I consider this to be a user error. The fix is to not do this.

[lroal]

Given the fresh wave of npm supply-chain incidents and the fact that Windows Defender is actively blocking esbuild.exe on some systems, I’d strongly prefer that esbuild ship without a postinstall hook (or at least make it fully optional and documented).

Why:

• CI hardening now defaults to --ignore-scripts in many orgs. Multiple advisories over the last few days/weeks explicitly recommend disabling lifecycle scripts to reduce blast radius from compromised packages. This isn’t hypothetical—researchers have documented ongoing npm credential-takeovers and wormable campaigns pushing malicious updates.
• Windows Defender false positives block the binary at install time. There are open reports where Defender blocks execution of esbuild.exe or flags the postinstall flow, which means a clean npm ci can fail for reasons outside the user’s control.
• Package managers are moving away from auto-running hooks. pnpm warns loudly (and can skip) postinstalls; many teams set ignore-scripts=true in .npmrc. Relying on a hook to “fix up” the install turns a build-time robustness concern into a security trade-off.

Concrete asks / proposals:

1. Document the exact responsibilities of postinstall. Evan’s comment helps a lot—please surface that in the README: what it checks, what breaks (or just slows down) when skipped, and which flags are incompatible (--ignore-scripts + --no-optional). Clear docs make it safer to adopt hardened defaults.
2. Make the “optimization” fully optional. If skipping the hook simply leaves a JS shim in node_modules/.bin and adds ~200ms process-spawn overhead, that’s an acceptable trade-off for many CI environments. Please treat this path as first-class and tested (no warnings, no failures).
3. Provide an explicit, opt-in fixer command. Example ideas:
   • A manual command (e.g. npx esbuild --finalize-install) that users can run locally if they want the fast path.
   • Or a tiny companion tool (esbuild-install) that teams can choose to execute after a locked-down npm ci.
     This preserves secure defaults while still enabling performance tuning.
4. Fail predictably without network/optionals. The --no-optional + script path is brittle in proxied/private registries. Please ensure the non-script path is resilient and that errors clearly explain how to recover (enable optionals, run the manual fixer, or install a platform-specific package).

---

TL;DR:
In today’s environment, teams are encouraged to default to --ignore-scripts. It would be great if esbuild treated that as a supported, documented path with no functional degradation (just the known, minor CLI shim overhead), and offered an explicit opt-in step for users who want the postinstall optimization. This balances security with the performance goals of the project.

[Tezra]

I'm leaving this open for the documentation update part of the ticket. @lroal The postintall already sounds pretty optional if for the most part it just save 1/5 of a second. @evanw I do admit that having an esbuild install and esbuild verify command(s) would be helpful over going into the package and manually running the postinstall after install. Similar to what Cypress has. Angular also does the OS specific optionals so not really sure that part can be improved.

[evanw]

I understand that people are concerned about install scripts. However, I think esbuild's install script is already set up for this?

It would be great if esbuild treated that as a supported, documented path with no functional degradation

As I just described above, the esbuild package should already work correctly when --ignore-scripts is present (setting aside package manager bugs, which do happen but which are outside of esbuild's control). Feel free to ignore scripts if you want. It has already been a supported workflow for many years now. I agree it should be mentioned in the documentation, but that's what this issue is about.

and offered an explicit opt-in step for users who want the postinstall optimization

I'm not planning on adding additional post-install complexity to the install flow. The binary version is already checked every time esbuild runs so if it doesn't match after installation, you'll just find out when you next try to run esbuild. And I don't think the slight performance improvement to the CLI is worth the additional complexity of having to use a special tool to enable it.

There are open reports where Defender blocks execution of esbuild.exe

Regarding Windows Defender: I'm not sure what to tell you there. If you're running anti-virus software on your computer that is preventing you from running esbuild, then there's nothing I can do about that. The presence or absence of an install script is not going to help you because presumably you are installing esbuild to then run it afterward. An anti-virus false positive will block esbuild whenever it runs, whether that's at install-time or after it's installed. The problem is instead between you and your anti-virus software and is up to you to fix.

[Tezra]

One more thing to add, the --ignore-scripts --no-optional case should probably also be mentioned in the install docs if the documentation is added elsewhere. The FAQ and Install guide where the first things I checked.