NodeSwitcher

NodeSwitcher is a Visual Studio Code extension that switches and installs Node.js versions from the status bar and sidebar, using the same version managers you already use on the command line.

The extension detects what is available on your PATH, runs the right CLI in a login shell, and applies the chosen Node to new integrated terminals via VS Code’s environment API (PATH, and N_PREFIX when using n).

Branding and Marketplace listing

Regenerate the PNGs with npm run readme:logo (runs automatically in vscode:prepublish before npx @vscode/vsce package).

Table of contents

• Branding and Marketplace listing
• Why NodeSwitcher
• Requirements
• Roadmap and platform testing
• Quick start
• Features
• Status bar
• Version picker (Quick Pick)
• Sidebar
• Project Node version
• Commands
• Settings
• Theme colors
• First-run “install requirements” panel
• Installer repair panel
• How switching works (technical)
• Troubleshooting
• Development
• License

Why NodeSwitcher

• Stay in the editor — pick a version from the status bar or the NODESWITCHER activity bar view without memorizing CLI flags.
• Install missing versions — when a version is not installed locally, NodeSwitcher can drive n / nvm install flows (with progress in the UI where applicable).
• Project-aware — reads declared Node constraints from your repo and highlights when the active version does not satisfy them.
• Recovery built in — guided repair for permission and prefix issues, plus a dedicated flow when n is installed but no default Node is active yet.

Requirements

Windows

• nvm-windows must be on your PATH when VS Code starts.
• NodeSwitcher does not use WSL nvm or the n binary on Windows.

macOS / Linux / Unix

• n and/or nvm-sh available in the environment VS Code inherits (typically the same as your login shell).
• If both are present, NodeSwitcher prefers n.
• Homebrew-style nvm paths and common Linux layouts are accounted for when locating nvm.sh.

General

• VS Code ^1.110.0 (see engines in package.json).
• A folder opened as a workspace is recommended so project detection (.nodeswitcher, package.json, etc.) works as intended.

Roadmap and platform testing

This section is the living status of validation and what we want to improve next. Reports from real setups (especially non-default shells and old OS releases) are welcome via your issue tracker or Marketplace Q&A.

Improvements we care about: clearer diagnostics when a manager is missing, more predictable behavior when PATH differs between GUI VS Code and a login terminal, and optional automated checks in CI for packaging and lint (full end-to-end n/nvm tests still require real OS environments).

Quick start

1. Install n / nvm-sh (Unix) or nvm-windows (Windows).
2. Install the NodeSwitcher extension from the Marketplace (or load the .vsix from source).
3. On first launch, review the NodeSwitcher — What you need webview (or run NodeSwitcher: Show install requirements from the Command Palette).
4. Click the Node entry in the status bar (or open the NODESWITCHER sidebar) and choose a version.
5. Open a new integrated terminal so it picks up the updated PATH (existing terminals keep their old environment).

Features

Status bar

• Shows the currently active Node version (as read from your manager, with sensible fallbacks).
• Click opens the version picker (Quick Pick).
• Optional minimal mode (icon-only) and configurable priority (see Settings).
• When the active version matches the project’s declared constraint, the status bar can use custom theme colors you control (see Theme colors).

Version picker (Quick Pick)

• Lists installed versions from n or nvm.
• Optional section for other available versions (remote listing), capped by nodeswitcher.maxOtherAvailableVersions.
• Supports install flows for versions not yet present locally.
• Reflects project pin / declared range when applicable.

Sidebar

• Activity bar: open the NODESWITCHER view (same logo as branding).
• Tree shows current, installed, togglable available versions, and actions to apply or open path & uninstall details for a version.
• Refresh and flows to resolve project mismatch when the workspace expects a different Node.

Project Node version

NodeSwitcher determines a “project” Node expectation by consulting sources in order (first match wins):

1. .nodeswitcher in the workspace root — JSON with a current field (and optional backend, history).
2. package.json engines.node (semver range).
3. .npmrc (node-version / related) in the project, then user home.
4. .nvmrc, .node-version, and similar files in the workspace.

Selecting a version from the picker can persist the choice into .nodeswitcher so the team shares the same pin.

Commands

Settings

Theme colors

You can override these in Settings (JSON) under workbench.colorCustomizations:

Defaults are green-tinted for dark, light, and high-contrast themes.

First-run “install requirements” panel

The first time the extension activates on your machine, it may open NodeSwitcher — What you need, summarizing:

• Windows: nvm-windows only; link to releases.
• macOS / Linux: n (brew / npm global) or nvm-sh; note that n wins when both exist; short note on nodeswitcher.nPrefix for permission issues.

Closing the panel (or Got it) records that you saw it. Use NodeSwitcher: Show install requirements to open it again without resetting that flag.

Installer repair panel

A webview (not static HTML only) drives repair by posting messages to the extension host, which can:

• Run a chained sequence of remediation steps until n ls or nvm probes succeed (with cancel support).
• Run individual steps (user prefix / N_PREFIX in settings, ownership hints, Homebrew n, nvm install script, sudo npm global install — as applicable to your OS).
• Open the NodeSwitcher install terminal, settings (nPrefix), external docs, retry last switch, and version picker.
• Show tailored UI for n_no_active (e.g. send n lts to the install terminal, poll until an active Node is detected).

Limits (by design): sudo passwords and interactive installer prompts still happen in the real integrated terminal; the webview orchestrates and reflects polling results.

How switching works (technical)

• Detection: The extension probes for n and nvm with timeouts and caches a backend choice (with invalidation when things break).
• Apply: For n, it runs n <version> (or equivalent) then resolves the node binary (with retries when n bin reports version required). For nvm, it uses a bash login wrapper with nvm use. On Windows, PowerShell + nvm-windows.
• Environment: vscode.EnvironmentVariableCollection prepends the Node bin directory to PATH for new terminals (workspace-scoped when a folder is open). For n, optional N_PREFIX is applied from nodeswitcher.nPrefix when set.
• Errors: Failures can open the error webview, notifications, and/or the repair webview depending on error class (e.g. Unix permission vs “no active Node” for n).

Troubleshooting

Development

cd nodeswitcher
npm install
npm run compile    # webpack dev build
npm run lint       # eslint
npm run package    # production webpack only
npm run build:release   # readme:logo → icons:build → package (same as vscode:prepublish)

• One-shot release (e.g. manual Marketplace upload): from nodeswitcher/, run npm run release -- patch (or minor / major). That runs lint → npm version bump → inserts a CHANGELOG.md section (Release X.Y.Z., edit later if you want) → publish:vsix → git add -A at repository root (every tracked change is included—clean up or commit beforehand) → commit chore(release): nodeswitcher vX.Y.Z → annotated tag vX.Y.Z → git push branch and tag. Append --no-push to stop before push. Then upload the VSIX from publishBuild/ (filename = name + version from package.json).

• Branding assets: media/logo.svg is the green gradient mark (activity bar / views). media/logo-status-glyph.svg is a currentColor shape for the status bar font (tints with STATUS_BAR_FOREGROUND, usually white). Run npm run readme:logo to regenerate media/readme-logo.png and media/extension-icon.png (128px store icon from logo.svg; both run in vscode:prepublish).

• Icons: npm run icons:build regenerates the status bar font from SVG (see scripts/build-status-font.mjs).

• VSIX: @vscode/vsce names the artifact {name}-{version}.vsix using package.json name and version only (no separate “build version”). Run npm run publish:vsix to produce publishBuild/nodeswitcher-<version>.vsix after prepublish. Plain npx @vscode/vsce package writes the same filename to the current directory.

License

See the repository’s license file (if present) or publisher terms on the Marketplace listing.

Links

• n (tj/n)
• nvm-sh
• nvm-windows
• VS Code Extension API
• Publishing extensions