# `file:` specifiers `specifier` refers to the value part of the `package.json`'s `dependencies` object. This is a semver expression for registry dependencies and URLs and URL-like strings for other types. ### Dependency Specifiers * A `file:` specifier is either an absolute path (eg `/path/to/thing`, `d:\path\to\thing`): * An absolute `file:///absolute/path` with any number of leading slashes being treated as a single slash. That is, `file:/foo/bar` and `file:///foo/bar` reference the same package. * … or a relative path (eg `../path/to/thing`, `path\to\subdir`). Leading slashes on a file specifier will be removed, that is 'file://../foo/bar` references the same package as same as `file:../foo/bar`. The latter is considered canonical. * Attempting to install a specifier that has a windows drive letter will produce an error on non-Windows systems. * A valid `file:` specifier points is: * a valid package file. That is, a `.tar`, `.tar.gz` or `.tgz` containing `/package.json`. * OR, a directory that contains a `package.json` Relative specifiers are relative to the file they were found in, or, if provided on the command line, the CWD that the command was run from. An absolute specifier found in a `package.json` or `npm-shrinkwrap.json` is probably an error as it's unlikely to be portable between computers and should warn. A specifier provided as a command line argument that is on a different drive is an error. That is, `npm install file:d:/foo/bar` is an error if the current drive is `c`. The point of this rule is that if we can't produce a relative path then it's an error. ### Specifier Disambiguation On the command line, plain paths are allowed. These paths can be ambiguous as they could be a path, a plain package name or a github shortcut. This ambiguity is resolved by checking to see if either a directory exists that contains a `package.json`. If either is the case then the specifier is a file specifier, otherwise it's a registry or github specifier. ### Specifier Matching A specifier is considered to match a dependency on disk when the `realpath` of the fully resolved specifier matches the `realpath` of the package on disk. ### Saving File Specifiers When saving to both `package.json` and `npm-shrinkwrap.json` they will be saved using the `file:../relative/path` form, and the relative path will be relative to the project's root folder. This is particularly important to note for the `npm-shrinkwrap.json` as it means the specifier there will be different then the original `package.json` (where it was relative to that `package.json`). When shrinkwrapping file specifiers, the contents of the destination package's `node_modules` WILL NOT be included in the shrinkwrap. If you want to lock down the destination package's `node_modules` you should create a shrinkwrap for it separately. This is necessary to support the mono repo use case where many projects file to the same package. If each project included its own `npm-shrinkwrap.json` then they would each have their own distinct set of transitive dependencies and they'd step on each other any time you ran an install in one or the other. NOTE: This should not have an effect on shrinkwrapping of other sorts of shrinkwrapped packages. ### Installation #### File type specifiers pointing at tarballs File-type specifiers pointing at a `.tgz` or `.tar.gz` or `.tar` file will install it as a package file in the same way we would a remote tarball. The checksum of the package file should be recorded so that we can check for updates. #### File type specifers pointing at directories File-type specifiers that point at directories will necessarily not do anything for `fetch` and `extract` phases. The symlink should be created during the `finalize` phase. The `preinstall` for file-type specifiers MUST be run AFTER the `finalize` phase as the symlink may be a relative path reaching outside the current project root and a symlink that resolves in `.staging` won't resolve in the package's final resting place. If the module is inside the package root that we're running the install for then dependencies of the linked package will be hoisted to the top level as usual. If the module is outside the package root then dependencies will be installed inside the linked module's `node_modules` folder. ### Removal Removal should remove the symlink. Removal MUST NOT remove the transitive dependencies IF they're installed in the linked module's `node_modules` folder. ### Listing In listings they should not include a version as the version is not something `npm` is concerned about. This also makes them easily distinguishable from symlinks of packages that have other dependency specifiers. If you had run: ``` npm install --save file:../a ``` And then run: ``` npm ls ``` You would see: ``` example-package@1.0.0 /path/to/example-package └── a → file:../a ``` ``` example-package@1.0.0 /path/to/example-package +-- a -> file:../a ``` Of note here: No version is included as the relevant detail is WHERE the package came from, not what version happened to be in that path. ### Outdated Local specifiers should only show up in `npm outdated` if they're missing and when they do, they should be reported as: ``` Package Current Wanted Latest Location a MISSING LOCAL LOCAL example-package ``` ### Updating If a dependency with a local specifier is already installed then `npm update` shouldn't do anything. If one is missing then it should be installed as if you ran `npm install`.