Codakey
Play
← Back to tj/n

How to Deploy & Use tj/n

n Node Version Manager Deployment and Usage Guide

This guide provides comprehensive instructions for deploying and using n, an interactive Node.js version manager.

Prerequisites

  • Operating System: macOS, Linux (including Windows Subsystem for Linux), or other Unix-like systems.
  • Shell: BASH (though n does not require you to use BASH as your command shell).
  • Node.js (Optional): An existing Node.js installation (e.g., via npm) can simplify n's initial installation.
  • curl: For downloading n directly.
  • npm (Optional): For installing n as a global package.
  • sudo (Optional): May be required for managing system-wide Node.js installations or ownership of directories.
  • Homebrew (macOS, Optional): For installing n via Homebrew.
  • MacPorts (macOS, Optional): For installing n via MacPorts.

Installation

n can be installed in several ways, depending on your current setup and preferences.

Via npm (Recommended if Node.js is already installed)

If you have an existing Node.js installation with npm, this is the simplest method:

npm install -g n

Addressing Permissions Issues: By default, n uses /usr/local as its root, which often requires root permissions. You have three options:

  1. Change Directory Ownership (Recommended for system-wide control): This grants your user ownership of the necessary directories, allowing n to manage Node.js versions without sudo for subsequent operations.

    # Create n cache folder and take ownership
sudo mkdir -p /usr/local/n
sudo chown -R $(whoami) /usr/local/n

# Ensure Node.js installation destination folders exist
sudo mkdir -p /usr/local/bin /usr/local/lib /usr/local/include /usr/local/share

# Take ownership of Node.js installation destination folders
sudo chown -R $(whoami) /usr/local/bin /usr/local/lib /usr/local/include /usr/local/share

  2. Use a Custom Location (N_PREFIX): Set the N_PREFIX environment variable to a directory where your user has write permissions (e.g., your home directory). See the Configuration section for details.

  3. Use sudo for n commands: Prefix n commands with sudo (e.g., sudo n install lts). This is generally less convenient and not recommended for regular use.

Direct Download

If npm is not available, you can download and install n directly.

To install n and an LTS Node.js version:

curl -fsSL https://raw.githubusercontent.com/tj/n/master/bin/n | bash -s install lts
# You can now install n globally via npm if desired:
npm install -g n

To download n as a standalone executable:

curl -fsSL -o /usr/local/bin/n https://raw.githubusercontent.com/tj/n/master/bin/n
chmod 0755 /usr/local/bin/n
n install lts # Install an LTS Node.js version

Third-Party Installers

  • macOS with Homebrew:

    brew install n

  • macOS with MacPorts:

    port install n

  • n-install (Linux and macOS): n-install places n and all managed Node.js versions within $HOME/n and configures your shell.

    curl -L https://bit.ly/n-install | bash

    After installation, n-install provides n-uninstall and n-update scripts.

Replacing a Previous Node.js Installation

If you're switching from another Node.js manager (e.g., Homebrew's Node.js), you might encounter conflicts. n will show different "installed" and "active" locations.

% n lts
     copying : node/20.12.2
   installed : v20.12.2 to /usr/local/bin/node
      active : v21.7.3 at /opt/homebrew/bin/node

To resolve this, ensure your PATH environment variable prioritizes the n managed Node.js path (typically /usr/local/bin if using default N_PREFIX) over other Node.js installations. You might need to uninstall previous Node.js versions managed by other tools. Refer to n's documentation on changing node location for detailed steps.

Configuration

n uses environment variables for custom configurations.

  • N_PREFIX: Specifies the root directory where n installs Node.js versions and stores its cache. Default: /usr/local Example: To install Node.js versions in your home directory:

    export N_PREFIX="$HOME/n"
# Add N_PREFIX/bin to your PATH
export PATH="$N_PREFIX/bin:$PATH"

    It's recommended to add these export commands to your shell's configuration file (e.g., .bashrc, .zshrc, .profile).

  • N_NODE_MIRROR: Overrides the default Node.js download mirror. Useful for custom mirrors or when experiencing slow downloads from the default. Default: https://nodejs.org/dist/ Example:

    export N_NODE_MIRROR="https://npmmirror.com/mirrors/node/"

  • N_NODE_ARCH: Specifies the architecture for Node.js binaries to download. Useful for cross-compilation or specific system requirements (e.g., ARM on an x86 machine). Default: Automatically detected. Example:

    export N_NODE_ARCH="arm64" # For ARM 64-bit architecture

  • N_npm_GLOBAL: Controls npm preservation behavior. See Preserving npm section. Default: true (preserves npm) Example:

    export N_npm_GLOBAL="false" # Do not preserve npm

Build & Run

n is a shell script and does not require a "build" step. You "run" it by executing commands.

Installing Node.js Versions

  • Install a specific version:

    n 10.16.0
n 18.17.1

  • Install the latest LTS (Long Term Support) version:

    n lts

  • Install the latest stable version:

    n latest

  • Install the latest version from a major release:

    n 16 # Installs the latest 16.x.x version

  • Install a specific version from a remote URL:

    n https://nodejs.org/dist/v14.17.0/node-v14.17.0-linux-x64.tar.xz

Interactive Version Selection

Run n without arguments to enter an interactive selection menu:

n

Use the up/down arrow keys (or j/k, ctrl+n/ctrl+p) to navigate.

  • Press Enter to install the selected version.
  • Press d to delete the selected version from the cache.
  • Press q to quit.

Using Downloaded Node.js Versions Without Reinstalling

n caches downloaded versions in N_PREFIX/n/versions. If a version is already downloaded, n will install it from the cache.

Removing Versions

  • Remove a specific version:

    n rm 10.16.0

  • Remove all cached versions (except the currently active one):

    n prune

Preserving npm

By default, n attempts to preserve your global npm packages when switching Node.js versions. If N_npm_GLOBAL is set to false, npm will not be preserved.

To explicitly disable npm preservation:

export N_npm_GLOBAL="false"
n lts # npm will not be preserved during this operation

Miscellaneous Commands

  • List installed versions:

    n ls

  • List remote versions available for download:

    n ls-remote

  • Display the path to the currently active Node.js binary:

    n bin

  • Run a command with a specific Node.js version:

    n use 14.17.0 my-script.js
n exec 16.x npm test

  • Clean the cache (removes all downloaded Node.js tarballs):

    n cache clean

Deployment

n is a local development tool for managing Node.js versions. It is not designed for "deployment" in the traditional sense of deploying an application to a server. Its purpose is to manage the Node.js runtime environment on a development machine or CI/CD runner.

However, you can incorporate n into your CI/CD pipelines or server setup scripts to ensure a specific Node.js version is used.

Example CI/CD Integration (e.g., GitHub Actions, GitLab CI):

# .github/workflows/ci.yml
name: CI

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    - name: Install Node.js with n
      run: |
        curl -fsSL https://raw.githubusercontent.com/tj/n/master/bin/n | bash -s install 18.17.1
        # Ensure n's installed node is in PATH
        echo "/usr/local/bin" >> $GITHUB_PATH
        node -v # Verify the version
        npm -v
    - name: Install dependencies
      run: npm ci
    - name: Run tests
      run: npm test

Example Server Setup Script:

#!/bin/bash

# Install n if not present
if ! command -v n &> /dev/null
then
    echo "n not found, installing..."
    curl -fsSL -o /usr/local/bin/n https://raw.githubusercontent.com/tj/n/master/bin/n
    chmod 0755 /usr/local/bin/n
fi

# Ensure n's default install location is owned by the current user
sudo mkdir -p /usr/local/n
sudo chown -R $(whoami) /usr/local/n
sudo mkdir -p /usr/local/bin /usr/local/lib /usr/local/include /usr/local/share
sudo chown -R $(whoami) /usr/local/bin /usr/local/lib /usr/local/include /usr/local/share

# Install the desired Node.js version
n install lts # Or n install 20.12.2

# Verify installation
node -v
npm -v

echo "Node.js environment configured."

Troubleshooting

  • "Permission denied" errors during installation or version switching:

    • Cause: n is trying to write to system directories (e.g., /usr/local) without sufficient permissions.
    • Solution:
      1. Change directory ownership: Follow the sudo chown commands in the Installation section to grant your user ownership of /usr/local/n, /usr/local/bin, etc.
      2. Use N_PREFIX: Set the N_PREFIX environment variable to a directory where your user has write permissions (e.g., $HOME/.n). Remember to add $N_PREFIX/bin to your PATH.
      3. Use sudo: As a last resort, prefix n commands with sudo (e.g., sudo n install lts).

  • Node.js version doesn't change after installation:

    • Cause: Your shell's PATH environment variable might be pointing to a different Node.js installation (e.g., one installed by Homebrew or a system package manager) that takes precedence over the n-managed one. Or, you might need to restart your shell.
    • Solution:
      1. Restart your shell: Close and reopen your terminal.
      2. Check PATH: Run echo $PATH. Ensure that the directory where n installs Node.js (typically /usr/local/bin or $N_PREFIX/bin) appears before any other Node.js installation paths.
      3. Identify conflicting installations: Run which node and which npm to see where your shell is finding these executables. You may need to uninstall conflicting Node.js versions or adjust your PATH permanently in your shell configuration file (.bashrc, .zshrc, .profile).
      4. Verify n's active version: Run n ls and check the o next to the active version. Then run n bin to see the path n expects.

  • n command not found:

    • Cause: The directory where n was installed (e.g., /usr/local/bin or $HOME/n/bin) is not in your PATH.
    • Solution:
      1. Verify n's location: Check if n exists in /usr/local/bin or your custom N_PREFIX/bin.
      2. Add to PATH: Add the directory containing the n executable to your PATH environment variable in your shell's configuration file. Example: export PATH="/usr/local/bin:$PATH" or export PATH="$HOME/n/bin:$PATH".

  • n does not work on Windows (PowerShell, Git Bash, Cygwin):

    • Cause: n is a BASH script and is not designed to run in native Windows shells or environments that emulate Unix with a compatibility layer like Cygwin.
    • Solution: Use n within Windows Subsystem for Linux (WSL) on Windows, where it is fully supported.

  • Slow download speeds for Node.js versions:

    • Cause: Geographic distance to the default Node.js mirror.
    • Solution: Set the N_NODE_MIRROR environment variable to a closer or faster mirror. See the Configuration section.

  • npm global packages are lost after switching Node.js versions:

    • Cause: n's npm preservation mechanism might be disabled or encountering an issue.
    • Solution:
      1. Ensure N_npm_GLOBAL is not explicitly set to false.
      2. Manually reinstall global packages after switching if preservation fails.
← Project overviewView alternatives to tj/n →