Skip to content

Commit 3ed764a

Browse files
docs: Clarify script working directory behavior (fixes #8305) (#8308)
<!-- What / Why --> <!-- Describe the request in detail. What it does and why it's being changed. --> 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 <!-- Examples: Related to #0 Depends on #0 Blocked by #0 Fixes #0 Closes #0 --> Fixes #8305 --------- Co-authored-by: Michael Smith <owlstronaut@github.com>
1 parent 2f30251 commit 3ed764a

File tree

1 file changed

+14
-5
lines changed

1 file changed

+14
-5
lines changed

docs/lib/content/using-npm/scripts.md

Lines changed: 14 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -228,6 +228,20 @@ Reasons for a package removal include:
228228

229229
Due to the lack of necessary context, `uninstall` lifecycle scripts are not implemented and will not function.
230230

231+
### Working Directory for Scripts
232+
233+
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.
234+
235+
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`.
236+
237+
#### Historical Behavior in Older npm Versions
238+
239+
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()).
240+
241+
For more details, see:
242+
- [npm v7 release notes](https://github.com/npm/cli/releases/tag/v7.0.0)
243+
- [Discussion about script working directory reliability in npm v6 and earlier](https://github.com/npm/npm/issues/12356)
244+
231245
### User
232246

233247
When npm is run as root, scripts are always run with the effective uid
@@ -350,11 +364,6 @@ file.
350364
preinstall or install script. If you are doing this, please consider if
351365
there is another option. The only valid use of `install` or `preinstall`
352366
scripts is for compilation which must be done on the target architecture.
353-
* Scripts are run from the root of the package folder, regardless of what the
354-
current working directory is when `npm` is invoked. If you want your
355-
script to use different behavior based on what subdirectory you're in, you
356-
can use the `INIT_CWD` environment variable, which holds the full path you
357-
were in when you ran `npm run`.
358367

359368
### See Also
360369

0 commit comments

Comments
 (0)