Document pnpm dlx path #580
Conversation
|
|
|
@karlhorky is attempting to deploy a commit to the pnpm Team on Vercel. A member of the Team first needs to authorize it. |
|
|
||
| * On Windows: **~/AppData/Local/pnpm/dlx** | ||
| * On macOS: **~/Library/Caches/pnpm/dlx** | ||
| * On Linux: **~/.cache/pnpm/dlx** |
There was a problem hiding this comment.
is this the correct path on Linux? I couldn't find where it was being retrieved / generated, after looking through the code in pnpm/pnpm#7835
There was a problem hiding this comment.
The correct path should be $CACHE_DIR/dlx for all platforms. The specific values of CACHE_DIR can be found here: https://pnpm.io/npmrc#cache-dir
The short answer is yes.
|
|
||
| You may also specify which exact version of the package you'd like to use: | ||
|
|
||
| ``` | ||
| pnpm dlx create-react-app@next ./my-app | ||
| ``` | ||
|
|
||
| The temporary location of the downloaded files is: | ||
|
|
||
| * On Windows: **~/AppData/Local/pnpm-cache/dlx** |
There was a problem hiding this comment.
is this the correct path on Windows? I couldn't find where it was being retrieved / generated, after looking through the code in pnpm/pnpm#7835
| @@ -238,7 +238,7 @@ After executing a dlx command, pnpm keeps a cache that omits the installation st | |||
| * On Linux: **~/.local/share/pnpm/store** | |||
| * Type: **path** | |||
|
|
|||
| The location where all the packages are saved on the disk. | |||
| The location where all the packages are saved on the disk (exception: [`pnpm dlx`](./cli/dlx.md)). | |||
There was a problem hiding this comment.
Or, another idea: also link to the cache-dir heading on the same page:
| The location where all the packages are saved on the disk (exception: [`pnpm dlx`](./cli/dlx.md)). | |
| The location where all the packages are saved on the disk (exception: [cache data](#cache-dir) incl. [dlx](./cli/dlx.md)). |
| The temporary location of the downloaded files is: | ||
|
|
||
| * On Windows: **~/AppData/Local/pnpm-cache/dlx** | ||
| * On macOS: **~/Library/Caches/pnpm/dlx** | ||
| * On Linux: **~/.cache/pnpm/dlx** | ||
|
|
There was a problem hiding this comment.
| The temporary location of the downloaded files is: | |
| * On Windows: **~/AppData/Local/pnpm-cache/dlx** | |
| * On macOS: **~/Library/Caches/pnpm/dlx** | |
| * On Linux: **~/.cache/pnpm/dlx** |
There was a problem hiding this comment.
They are just a repeat of cache-dir section but with dlx suffix. So I don't think this part is necessary.
There was a problem hiding this comment.
I hope that this part will not be removed
to me, this is the main value of the PR: to explicitly list out the paths to the pnpm dlx files.
this will allow for:
- easy searching through the docs for possible paths for a particular package
- search engines + LLMs retrieving and surfacing this information for searchers, in case the docs search doesn't provide an experience that is discoverable enough
There was a problem hiding this comment.
The location of the cache dir is not necessary fixed. Maybe in the future, it will change. I don't think as a developer, we would like to duplicate our effort.
What I suggest is, instead of explicitly listing out the resolved values of the dlx cache paths, just mention that they are saved in $CACHE_DIR/dlx is enough.
There was a problem hiding this comment.
ok, I still disagree - strongly prefer having the resolved paths
$CACHE_DIR is not clear, and indicates an environment variable, which is not observable / discoverable in the case of the default paths
The location of the cache dir is not necessary fixed. Maybe in the future, it will change. I don't think as a developer, we would like to duplicate our effort.
I think if the cache dir does change in future, it will be probably a grep + replace across the whole codebase (already needs to be updated in the cache-dir section on the .npmrc docs page), so I would argue, probably not extra effort to update the docs
There was a problem hiding this comment.
$CACHE_DIRis not clear, and indicates an environment variable, which is not observable / discoverable in the case of the default paths
It is just my personal habit to communicate with developers in issues and PRs. It is essentially the same as saying $THIS_YEAR on Reddit. I do not suggest you use $CACHE_DIR literally. You can change it to "a subdirectory named dlx inside the [cache-dir](link)" or something.
it will be probably a grep + replace across the whole codebase
No one is expected to grep + replace everything all the time, so unless the person who would edit it remember the duplicated docs (which is unlikely), they are going to forget it.
There was a problem hiding this comment.
You can change it to "a subdirectory named
dlxinside the[cache-dir](link)" or something.
this is somewhat better, but still leaves out parts of the paths, which may be what users are searching for
I still strongly believe that the tradeoff is worth it - to me, the value of explicit, resolved paths far outweighs the possible future developer error because of the duplication
| @@ -238,7 +238,7 @@ After executing a dlx command, pnpm keeps a cache that omits the installation st | |||
| * On Linux: **~/.local/share/pnpm/store** | |||
| * Type: **path** | |||
|
|
|||
| The location where all the packages are saved on the disk. | |||
| The location where all the packages are saved on the disk (exception: [`pnpm dlx`](./cli/dlx.md)). | |||
There was a problem hiding this comment.
There is no exception. The files for dlx are still stored in the store directory. They are reflinked or hardlinked from the store directory to the dlx cache (same as when you pnpm install on one of your Node.js projects). In fact, pnpm dlx is just pnpm install on a temporary dlx cache directory.
| The location where all the packages are saved on the disk (exception: [`pnpm dlx`](./cli/dlx.md)). | |
| The location where all the packages are saved on the disk. |
There was a problem hiding this comment.
if the pnpm team thinks that there is no need to clarify in this position in the docs, then feel free to remove this change of mine
I added it because I think it's common to run into the "store location" docs when searching for locations for where pnpm stores files
but users won't always be looking for these particular paths, so linking elsewhere, where other paths can be found was my aim here
Alternative
an alternative would be a single page which ONLY listed out directory paths that pnpm used (regardless of whether it's the files or symlinks), so that it's centralized in one place...
bigger PR though
There was a problem hiding this comment.
I guess the overarching concern is when cleaning up disk spaces, the user needs to know the locations to remove?
There are 3 types of locations need to be concern about:
- Your projects'
node_modules. - The store directory.
- The cache directory.
The files used by dlx are well within the 3 confines above (technically 2). And if you remove the 3 above, you should clean up dlx.
Maybe you can document the 3 locations above (if the documentation doesn't have it already). But to word it as an "exception" would confuse the users.
There was a problem hiding this comment.
I guess the overarching concern is when cleaning up disk spaces, the user needs to know the locations to remove?
no, I wasn't concerned with cleaning up disk space
my use case (mentioned in the PR description above) is to find the location of the files that are currently running when running the dlx commands, so that I can modify the files:
I was having trouble finding the location of packages such as
create-playwrightwhen running any of these commands (I was trying to edit them to verify that my PR tocreate-playwrightwould behave as I wanted):pnpm dlx create-playwright pnpx create-playwright pnpm create playwright
There was a problem hiding this comment.
Well, dlx is still not an exception here. It still uses the same store-dir and its "projects" are still in the same cache-dir.
There was a problem hiding this comment.
I didn't mean to suggest that dlx was an exception
I'm trying to describe use cases of developers who:
- use pnpm (maybe using
--global, maybe usingdlx) - who want to modify the
node_modulesfiles that are currently being run
the problems I'm trying to alleviate with this PR (maybe not clear, I'll copy this above to the PR description):
these developers need to find the files. it's currently not easy and centralized to find the locations of these files.
There was a problem hiding this comment.
it's currently not easy and centralized to find the locations of these files.
I see. You should create an issue and discuss it with @zkochan.
There was a problem hiding this comment.
I edited the PR description to provide a clearer picture into the motivations.
If it needs to be copied to an issue, I can do this too.
There was a problem hiding this comment.
If it needs to be copied to an issue, I can do this too.
I meant regarding what you said about not easy to find a centralized location that list all these locations of --global, dlx, etc. I didn't mean just dlx.
| @@ -14,14 +14,20 @@ needing to install it under another project, you can run: | |||
| pnpm dlx create-react-app ./my-app | |||
| ``` | |||
|
|
|||
| This will fetch `create-react-app` from the registry and run it with the given arguments. | |||
| This will fetch `create-react-app` from the registry, download it to a temporary location (see below) and run it with the given arguments. | |||
There was a problem hiding this comment.
pnpm dlx will download it to the store then reflink the files from the store to the dlx cache dir. This works similar to pnpm install.
There was a problem hiding this comment.
ok right, I was unsure whether this was technically 100% correct wording here. I was trying to keep the explanation simple
|
You should not edit the temporary files created by dlx. I am not against additional docs but I also don't want the users to think it is OK to go there and make changes manually. That is not a proper way to test your changes locally. |
Yeah, I understand the sentiment of not wanting to officially recommend something that users could unintentionally misuse and cause confusion. On the other hand, I think there are a lot of things that users could already misuse to cause problems for themselves. That aside, there is also a benefit to knowing how tools work and where they are saving files. And for power users, it can be a very helpful tool to be able to quickly jump in to the "
Hmm... why do you think that? As I mentioned above, I think it's a pretty common workflow for people to edit the |
|
To be clear though, I don't intend for this PR to add language for an official pnpm recommendation that users edit those files - power users will decide to do this on their own anyway without any recommendation. |
If you want to do that, then use a temporary project. Create a new directory, run |
Seems like an ok alternative. But it's extra setup time and friction, and causes the newly-installed package to be run in a different way than the globally installed package. So in a lot of cases, for small fixes or prototyping, I wouldn't use this.
Interesting, I didn't know that behavior about dlx. It's something to be extra cautious about. But about "Don't modify globally installed packages." - any other reason than "dlx can remove your changes at any time"? |
I was having trouble finding the location of packages such as
create-playwrightwhen running any of these commands (I was trying to edit them to verify that my PR tocreate-playwrightwould behave as I wanted):Why
Use cases are developers who:
--global, maybe usingdlx)node_modulesfiles that are currently being runThese developers need to find the files to edit. It's currently not easy or centralized to find the locations of these files.
This PR only deals with the "easy" part by explicitly listing out the resolved paths to these locations.
Alternatives Considered
A single page which ONLY lists out all directory paths that pnpm uses (regardless of whether it's the files or symlinks), so that it's centralized in one place.
It could potentially replace the paths listed on various sections of the
npmrcdocs page.Bigger PR though.
cc @KSXGitHub I think this may have been implemented in pnpm/pnpm#7835