docs: Clarify script working directory behavior (fixes #8305) (#8308)

tarekwfa0110 · owlstronaut · web-flow · commit 3ed764aa08f2 · 2025-05-21T10:22:31.000-07:00
This pull request updates the documentation for npm scripts, specifically the `scripts.md` file. **What:** - Clarified that scripts are always run from the root of the package folder in npm v7 and later. - Added a "Historical Behavior in Older npm Versions" section to explain that while generally true for npm v6 and earlier, there were inconsistencies and that `process.cwd()` could be used as a safeguard. - Ensured the `INIT_CWD` environment variable is mentioned as a way for scripts to access the original working directory. - Provided links to the npm v7 release notes and the relevant GitHub issue discussing script working directory reliability in older versions. **Why:** This change aims to provide clearer and more accurate documentation regarding the working directory of npm scripts, addressing potential confusion, especially for users working with or migrating from older npm versions. This helps resolve the points raised in issue #8305. ## References  Fixes #8305 --------- Co-authored-by: Michael Smith <owlstronaut@github.com>
diff --git a/docs/lib/content/using-npm/scripts.md b/docs/lib/content/using-npm/scripts.md
@@ -228,6 +228,20 @@ Reasons for a package removal include:
 
 Due to the lack of necessary context, `uninstall` lifecycle scripts are not implemented and will not function.
 
+### Working Directory for Scripts
+
+Scripts are always run from the root of the package folder, regardless of what the current working directory is when `npm` is invoked. This means your scripts can reliably assume they are running in the package root.
+
+If you want your script to behave differently based on the directory you were in when you ran `npm`, you can use the `INIT_CWD` environment variable, which holds the full path you were in when you ran `npm run`.
+
+#### Historical Behavior in Older npm Versions
+
+For npm v6 and earlier, scripts were generally run from the root of the package, but there were rare cases and bugs in older versions where this was not guaranteed. If your package must support very old npm versions, you may wish to add a safeguard in your scripts (for example, by checking process.cwd()).
+
+For more details, see:
+- [npm v7 release notes](https://github.com/npm/cli/releases/tag/v7.0.0)
+- [Discussion about script working directory reliability in npm v6 and earlier](https://github.com/npm/npm/issues/12356)
+
 ### User
 
 When npm is run as root, scripts are always run with the effective uid
@@ -350,11 +364,6 @@ file.
   preinstall or install script. If you are doing this, please consider if
   there is another option. The only valid use of `install` or `preinstall`
   scripts is for compilation which must be done on the target architecture.
-* Scripts are run from the root of the package folder, regardless of what the
-  current working directory is when `npm` is invoked. If you want your
-  script to use different behavior based on what subdirectory you're in, you
-  can use the `INIT_CWD` environment variable, which holds the full path you
-  were in when you ran `npm run`.
 
 ### See Also
 
