From 156ad6f7caad0bfe29daacc8d155a05bd153ad25 Mon Sep 17 00:00:00 2001 From: Zoltan Kochan Date: Fri, 7 Jan 2022 17:35:38 +0200 Subject: [PATCH] Add more information about node-linker=hoisted --- docs/limitations.md | 11 ++--------- docs/motivation.md | 10 ++++++++-- docs/npmrc.md | 8 +++++++- 3 files changed, 17 insertions(+), 12 deletions(-) diff --git a/docs/limitations.md b/docs/limitations.md index 6b4af31d38e6..7a457be7d90a 100644 --- a/docs/limitations.md +++ b/docs/limitations.md @@ -6,24 +6,17 @@ title: Limitations 1. `npm-shrinkwrap.json` and `package-lock.json` are ignored. Unlike pnpm, npm can install the same `name@version` multiple times and with different sets of dependencies. npm's lockfile is designed to reflect the flat `node_modules` -layout, however, as pnpm cannot create a similar layout, it cannot respect +layout, however, as pnpm creates an isolated layout by default, it cannot respect npm's lockfile format. See [pnpm import] if you wish to convert a lockfile to pnpm's format, though. -2. pnpm can't publish npm packages with `bundledDependencies`. Currently, there -are no plans to add support for `bundledDependencies` either, as they do not -work very consistently in publishing, even on npm. Instead, we recommend you use -an actual package bundler, like webpack, rollup, or ESBuild. -3. Binstubs (files in `node_modules/.bin`) are always shell files, not +1. Binstubs (files in `node_modules/.bin`) are always shell files, not symlinks to JS files. The shell files are created to help pluggable CLI apps in finding their plugins in the unusual `node_modules` structure. This is very rarely an issue and if you expect the file to be a JS file, reference the original file directly instead, as described in [#736]. -4. Node's [--preserve-symlinks] flag does not work when executed in a project -that uses pnpm. Got an idea for workarounds for these issues? [Share them.](https://github.com/pnpm/pnpm/issues/new) [pnpm import]: cli/import.md [#736]: https://github.com/pnpm/pnpm/issues/736 -[--preserve-symlinks]: https://nodejs.org/api/cli.html#cli_preserve_symlinks diff --git a/docs/motivation.md b/docs/motivation.md index 76b99caf9b57..26f37060b138 100644 --- a/docs/motivation.md +++ b/docs/motivation.md @@ -28,12 +28,18 @@ projects and dependencies, and you have a lot faster installations! [![](/img/node-modules-structure.jpg)](https://twitter.com/xiaokedada/status/1471691763102679041/photo/1) -When installing dependencies with npm, all packages are hoisted to the root of the +When installing dependencies with npm or Yarn Classic, all packages are hoisted to the root of the modules directory. As a result, source code has access to dependencies that are not added as dependencies to the project. -pnpm uses symlinks to add only the direct dependencies of the project into the root of the modules directory. +By default, pnpm uses symlinks to add only the direct dependencies of the project into the root of the modules directory. If you'd like more details about the unique `node_modules` structure that pnpm creates and why it works fine with the Node.js ecosystem, read: - [Flat node_modules is not the only way](/blog/2020/05/27/flat-node-modules-is-not-the-only-way) - [Symlinked node_modules structure](symlinked-node-modules-structure.md) + +::: tip + +If your tooling doesn't work well with symlinks, you may still use pnpm and set the [node-linker](npmrc#node-linker) setting to `hoisted`. This will instruct pnpm to create a node_modules directory that is similar to those created by npm and Yarn Classic. + +::: diff --git a/docs/npmrc.md b/docs/npmrc.md index dfaab5938290..9f848e290a77 100644 --- a/docs/npmrc.md +++ b/docs/npmrc.md @@ -133,11 +133,17 @@ Added in: v5.9.0 Defines what linker should be used for installing Node packages. * **isolated** - dependencies are symlinked from a virtual store at `node_modules/.pnpm`. -* **hoisted** - a flat `node_modules` without symlinks is created. Same as the `node_modules` created by npm or Yarn Classic. Choose this linker if you have issues with symlinks (for instance, for a React Native project). +* **hoisted** - a flat `node_modules` without symlinks is created. Same as the `node_modules` created by npm or Yarn Classic. Legitimate reasons to use this setting: + 1. Your tooling doesn't work well with symlinks. A React Native project will most probably only work if you use a hoisted `node_modules`. + 1. Your project is deployed to a serverless hosting provider. Some serverless providers (for instance, AWS Lambda) don't support symlinks. An alternative solution for this problem is to bundle your application before deployment. + 1. If you want to publish your package with [`"bundledDependencies"`]. + 1. If you are running Node.js with the [--preserve-symlinks] flag. * **pnp** - no `node_modules`. Plug'n'Play is an innovative strategy for Node that is [used by Yarn Berry][pnp]. It is recommended to also set `symlink` setting to `false` when using `pnp` as your linker. [pnp]: https://yarnpkg.com/features/pnp +[--preserve-symlinks]: https://nodejs.org/api/cli.html#cli_preserve_symlinks +[`"bundledDependencies"`]: https://docs.npmjs.com/cli/v8/configuring-npm/package-json#bundleddependencies ### symlink