Skip to content

Commit 7e56c67

Browse files
shadowspawnshadowspawn
authored
Docs for switching node directory (#802)
1 parent 010c596 commit 7e56c67

File tree

2 files changed

+128
-0
lines changed

2 files changed

+128
-0
lines changed

‎README.md

+13
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ Node.js version management: no subshells, no profile setup, no convoluted API, j
1313
- [Supported Platforms](#supported-platforms)
1414
- [Installation](#installation)
1515
- [Third Party Installers](#third-party-installers)
16+
- [Replacing a previous node install](#replacing-a-previous-node-install)
1617
- [Installing Node.js Versions](#installing-nodejs-versions)
1718
- [Specifying Node.js Versions](#specifying-nodejs-versions)
1819
- [Removing Versions](#removing-versions)
@@ -87,6 +88,18 @@ n-install sets both `PREFIX` and `N_PREFIX` to `$HOME/n`, installs `n` to `$HOME
8788

8889
As a result, both `n` itself and all Node.js versions it manages are hosted inside a single, optionally configurable directory, which you can later remove with the included `n-uninstall` script. `n-update` updates `n` itself to the latest version. See the [n-install repo](https://github.com/mklement0/n-install) for more details.
8990

91+
### Replacing a previous node install
92+
93+
Changing from a previous Node.js installed to a different location may involve a few extra steps. See docs for [changing node location]((./docs/changing-node-location.md)) for a walk-through example of switching from using Homebrew to using `n` to manage Node.js.
94+
95+
You have a problem with multiple versions if after installing node you see the "installed" and "active" locations are different:
96+
```console
97+
% n lts
98+
copying : node/20.12.2
99+
installed : v20.12.2 to /usr/local/bin/node
100+
active : v21.7.3 at /opt/homebrew/bin/node
101+
```
102+
90103
## Installing Node.js Versions
91104

92105
Simply execute `n <version>` to download and install a version of Node.js. If `<version>` has already been downloaded, `n` will install from its cache.

‎docs/changing-node-location.md

+115
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
# Switching To `n` Managed Node.js
2+
3+
If you already have Node.js installed to a different root than `n` uses, you can easily end up with multiple copies of node (and npm, and npx, and globally installed packages!). Some common situations are you already had Node.js installed using your Linux package manager, or using another node version manager, or using say Homebrew. The two main ways you might resolve this are:
4+
5+
- uninstall from the old directory and reinstall to the new directory
6+
- put the `bin` directory that `n` uses early in the `PATH` environment variable, so the `n` installed node is found first
7+
8+
The simplest setup to understand is the first one. Just have one version of `node` installed.
9+
10+
Let's walk-through the process of switching over from using Homebrew as an example. Let's start off with Node.js installed, `npm` updated, and an example global npm package. The key point is there are two install prefixes involved:
11+
12+
- old: `/opt/homebrew`
13+
- new: `/usr/local`
14+
15+
```console
16+
% brew install node
17+
% npm install --global npm@latest
18+
% npm install --global @shadowspawn/forest-arborist
19+
% brew list node
20+
/opt/homebrew/Cellar/node/21.7.3/bin/node
21+
/opt/homebrew/Cellar/node/21.7.3/bin/npm
22+
/opt/homebrew/Cellar/node/21.7.3/bin/npx
23+
/opt/homebrew/Cellar/node/21.7.3/etc/bash_completion.d/npm
24+
/opt/homebrew/Cellar/node/21.7.3/include/node/ (107 files)
25+
/opt/homebrew/Cellar/node/21.7.3/libexec/bin/ (2 files)
26+
/opt/homebrew/Cellar/node/21.7.3/libexec/lib/ (2012 files)
27+
/opt/homebrew/Cellar/node/21.7.3/share/doc/ (2 files)
28+
/opt/homebrew/Cellar/node/21.7.3/share/man/man1/node.1
29+
% command -v node
30+
/opt/homebrew/bin/node
31+
% command -v npm
32+
/opt/homebrew/bin/npm
33+
% npm prefix --global
34+
/opt/homebrew
35+
```
36+
37+
Before we start transferring, list the global npm packages in the "old" location. We will refer back to this list.
38+
39+
```console
40+
% npm list --global
41+
/opt/homebrew/lib
42+
├── @shadowspawn/[email protected]
43+
└── [email protected]
44+
```
45+
46+
We could clean out the old location first, but let's install `n` and another copy of node and see what that looks like. We end up with two versions of node, and the active one is still the Homebrew managed version.
47+
48+
```console
49+
% brew install n
50+
% n lts
51+
installing : node-v20.12.2
52+
mkdir : /usr/local/n/versions/node/20.12.2
53+
fetch : https://nodejs.org/dist/v20.12.2/node-v20.12.2-darwin-arm64.tar.xz
54+
copying : node/20.12.2
55+
installed : v20.12.2 to /usr/local/bin/node
56+
active : v21.7.3 at /opt/homebrew/bin/node
57+
% command -v node
58+
/opt/homebrew/bin/node
59+
% which -a node
60+
/opt/homebrew/bin/node
61+
/usr/local/bin/node
62+
% command -v npm
63+
/opt/homebrew/bin/npm
64+
% command -v npx
65+
/opt/homebrew/bin/npx
66+
% n doctor
67+
<...>
68+
69+
CHECKS
70+
71+
Checking n install destination is in PATH...
72+
good
73+
74+
Checking n install destination priority in PATH...
75+
⚠️ There is a version of node installed which will be found in PATH before the n installed version.
76+
77+
Checking npm install destination...
78+
⚠️ There is an active version of npm shadowing the version installed by n. Check order of entries in PATH.
79+
installed : /usr/local/bin/npm
80+
active : /opt/homebrew/bin/npm
81+
82+
<...>
83+
```
84+
85+
Now let's switch over. Delete everything from the old location. Delete all the global npm packages _except_ npm itself, then delete npm, then delete node.
86+
87+
```console
88+
npm uninstall --global @shadowspawn/forest-arborist
89+
90+
npm uninstall --global npm
91+
92+
brew uninstall node
93+
```
94+
95+
Check the active binaries are now the ones installed by `n`:
96+
```console
97+
% command -v node
98+
/usr/local/bin/node
99+
% command -v npm
100+
/usr/local/bin/npm
101+
% command -v npx
102+
/usr/local/bin/npx
103+
```
104+
105+
And lastly, reinstall the global npm packages you started with:
106+
```
107+
% npm prefix --global
108+
/usr/local
109+
% npm install --global npm@latest
110+
% npm install --global @shadowspawn/forest-arborist
111+
% npm list -g
112+
/usr/local/lib
113+
├── @shadowspawn/[email protected]
114+
└── [email protected]
115+
```

0 commit comments

Comments
 (0)