Skip to content

Conversation

@MaxBlack-dev
Copy link
Contributor

Description

This PR updates the documentation to clarify that the prepare lifecycle script runs on all npm install commands, not just those "without any arguments".

Changes

  • Update prepare script documentation to reflect it runs with --production and other flags
  • Remove misleading "without any arguments" phrasing that suggested it only runs on plain npm install

Fixes

Closes #4027

Context

Since npm 7, the prepare script runs on npm install --production, which differs from npm 6 behavior and contradicts the current documentation. This has caused confusion for users migrating from npm 6 who expected devDependencies (often required by prepare scripts) to be skipped during production installs.

The documentation currently states prepare "Runs on local npm install without any arguments", which is misleading. It actually runs for all install operations, including:

  • npm install (no arguments)
  • npm install --production
  • npm install --omit=dev
  • Other install variations

Users who need to skip the prepare script during production installs should use npm install --production --ignore-scripts as a workaround.

@MaxBlack-dev MaxBlack-dev requested a review from a team as a code owner December 3, 2025 21:11
Copy link
Contributor

@owlstronaut owlstronaut left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wonder if we could add nuance to clarify the distinction between package arguments and flags since it won't run when a package argument is given?

@MaxBlack-dev MaxBlack-dev force-pushed the docs/4027-prepare-production-clean branch from f049119 to ca5e544 Compare December 4, 2025 19:25
@MaxBlack-dev
Copy link
Contributor Author

Thank you for the feedback! I've updated the documentation to clarify the distinction between flags and package arguments.

Updated Text

The prepare script description now reads:

Runs on local npm install without package arguments (runs with flags like --production or --omit=dev, but does not run when installing specific packages like npm install express)

This makes it clear that:

  • Runs with npm install (no arguments)
  • Runs with npm install --production (flags are okay)
  • Runs with npm install --omit=dev (flags are okay)
  • Does NOT run with npm install express (specific package arguments)

This should help users understand when the prepare script will execute.

Copy link
Contributor

@owlstronaut owlstronaut left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the update!

@owlstronaut owlstronaut merged commit 2030250 into npm:latest Dec 4, 2025
8 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[BUG] npm install --production runs scripts

2 participants