Automatic Node.js Version Switching Plugin for VS Code

Background

I was learning Next.js, which requires Node ≥ v18.17.0, while an older company project is limited to Node ≤ v16.20.0, so I used v16.20.0 at work and v20.0.0 after hours. Forgetting to switch versions with n caused frequent errors, prompting me to create a plugin that automatically switches Node versions per project.

n and nvm implementation principles

n implementation

n stores all Node versions under /usr/local/n/versions , each in a subdirectory named after the version.

Switching copies the selected version's /usr/local/n/versions/{version}/bin/node binary to /usr/local/bin , making the change global.

Therefore, n switches versions globally and cannot be configured per directory.

nvm implementation

When installing a specific Node version, nvm downloads the pre‑compiled binary and extracts it to ~/.nvm/versions/node/{version} , keeping each version isolated.

Running nvm use <version> prepends the selected version's bin directory to the PATH environment variable, so subsequent node or npm commands use that version.

To load nvm in new shell sessions, users add a source ~/.nvm/nvm.sh line to their ~/.bashrc or ~/.zshrc files.

Thus, nvm allows independent Node versions per shell session.

Node script

Implementation idea

Read the nodeVersion field from the project's package.json ; if present, invoke n to switch to that version before starting the project.

Demo code

const { spawn } = require('child_process');
const { readFileSync } = require('fs');
const path = require('path');
const { cwd } = require('process');

let packageJson = readFileSync(path.join(cwd(), '/package.json')).toString();
if (packageJson) {
  packageJson = JSON.parse(packageJson);
}
if (packageJson.nodeVersion) {
  // Execute n command
  spawn('n', [packageJson.nodeVersion]);
}

The demo reads nodeVersion from package.json and runs n to switch versions.

VS Code plugin

Implementation idea

Because projects are usually started from VS Code's integrated terminal, the plugin detects the opened terminal, reads the project's nodeVersion , and sends the appropriate nvm use command to the terminal without affecting other projects.

Implementation steps

Create VS Code extension project

npm install -g yo
yo code

Core code (extension.js)

// extension.js
const { existsSync, readFileSync } = require('fs');
const { join } = require('path');
const vscode = require('vscode');
const { exec } = require('child_process');

function commandExistsInShell(shell, command, callback) {
  let execCommand = `type ${command}`;
  if (shell.includes('zsh')) {
    execCommand = `source ~/.zshrc && type ${command}`;
  }
  exec(execCommand, { shell }, (error, stdout, stderr) => {
    if (error || stderr) return callback(false);
    callback(true);
  });
}

function activate() {
  vscode.window.onDidOpenTerminal((terminal) => {
    if (!vscode.workspace.workspaceFolders) return;
    const workspacePath = vscode.workspace.workspaceFolders[0].uri.fsPath;
    const pkgPath = join(workspacePath, '/package.json');
    if (!existsSync(pkgPath)) return;
    const pkgStr = readFileSync(pkgPath, 'utf8').toString();
    if (!pkgStr) return;
    try {
      const pkg = JSON.parse(pkgStr);
      if (!pkg.nodeVersion) return;
      const { shellPath } = terminal.creationOptions;
      commandExistsInShell(shellPath, 'nvm', (exists) => {
        if (exists) {
          let command = `source ~/.nvm/nvm.sh && nvm ls ${pkg.nodeVersion}`;
          if (shellPath.includes('fish')) command = `nvm ls ${pkg.nodeVersion}`;
          exec(command, { shell: shellPath }, (error, stdout, stderr) => {
            if (error || stderr) {
              vscode.window.showErrorMessage(`${pkg.nodeVersion} version not found, install?`, 'Yes', 'No')
                .then((value) => {
                  if (value === 'Yes') terminal.sendText(`nvm install ${pkg.nodeVersion}`, true);
                });
              return;
            }
            if (stdout) {
              terminal.sendText('nvm use ' + pkg.nodeVersion, true);
            }
          });
        } else {
          vscode.window.showErrorMessage('nvm command not found, install it first.', 'View guide', 'Cancel')
            .then((value) => {
              if (value === 'View guide') vscode.env.openExternal(vscode.Uri.parse('https://github.com/nvm-sh/nvm'));
            });
        }
      });
    } catch (e) {}
  });
}

function deactivate() {}
module.exports = { activate, deactivate };

Demo effect

Conclusion

The extension has been published to the VS Code Marketplace (search for auto-switch-node-version or visit the provided link). Users must install nvm first; installation instructions are linked. Source code is available at GitHub .