Node Version Runner

English | 中文

English

Node Version Runner is a VS Code extension for running package scripts with the Node.js version required by the current workspace.

It reads scripts from the workspace package.json, lets you choose one with Quick Pick, switches to the detected Node.js version, and runs the selected script in the VS Code terminal.

nvm use <version> && npm run <script>

Features

• Read npm scripts from the workspace root package.json.
• Run scripts from the Command Palette with Node Version Runner: Run npm Script.
• Show a persistent Node Script button in the VS Code status bar.
• Support npm, pnpm, and yarn.
• Detect the workspace Node.js version from common project files.

Node Version Resolution

The Node.js version is resolved in this order:

1. nodeVersionRunner.nodeVersion setting
2. .nvmrc
3. .node-version
4. package.json engines.node
5. 14

Requirements

• VS Code 1.85.0 or later.
• nvm installed and available in the terminal.
• A workspace with a package.json file.
• At least one script defined in package.json.

Example:

{
  "scripts": {
    "dev": "vite",
    "build": "vite build"
  }
}

Usage

1. Open a Node.js project folder in VS Code.

2. Open the Command Palette:

   Cmd + Shift + P
   

   On Windows or Linux:

   Ctrl + Shift + P
   

3. Run:

   Node Version Runner: Run npm Script
   

4. Select a script from the list.

5. The extension opens a terminal and runs the script with the detected Node.js version.

You can also click the Node Script button in the bottom status bar.

Settings

Search for Node Version Runner in VS Code settings.

Example VS Code settings.json:

{
  "nodeVersionRunner.nodeVersion": "18",
  "nodeVersionRunner.packageManager": "pnpm",
  "nodeVersionRunner.showStatusBarButton": true
}

Install to VS Code

Development Mode

Use this mode when developing or debugging the extension.

1. Open this extension folder in VS Code.
2. Press F5 to launch an Extension Development Host.
3. In the new VS Code window, open a Node.js project.
4. Run Node Version Runner: Run npm Script from the Command Palette, or click Node Script in the status bar.

This mode does not permanently install the extension into your main VS Code window.

VSIX Install

Use this mode when you want to install the extension into VS Code.

1. Install the VS Code extension packaging tool:

   npm install -g @vscode/vsce
   

2. Package the extension from this project root:

   vsce package
   

3. Install the generated .vsix file:

   code --install-extension node-version-runner-0.1.0.vsix --force
   

4. Reload or restart VS Code.

You can also install it from the VS Code Extensions panel:

1. Open Extensions.
2. Click ....
3. Select Install from VSIX....
4. Choose the generated .vsix file.

Status Bar

The extension activates after VS Code startup and shows a Node Script button in the bottom status bar when nodeVersionRunner.showStatusBarButton is enabled.

If the button does not appear:

• Confirm the extension is enabled.
• Confirm nodeVersionRunner.showStatusBarButton is true.
• Reload VS Code with Developer: Reload Window.
• Reinstall the latest .vsix if you changed package.json.

Windows Notes

On native Windows, install nvm-windows first. The extension uses cmd.exe for terminal commands, so this command form works:

nvm use 14 && npm run serve

On WSL, install Linux/macOS nvm inside WSL. VS Code Remote WSL runs the extension in the Linux environment.

Troubleshooting

No scripts found

Make sure the opened workspace root contains package.json and that scripts is not empty.

Wrong Node.js version

Check the version sources in this order:

1. VS Code setting nodeVersionRunner.nodeVersion
2. .nvmrc
3. .node-version
4. package.json engines.node

nvm command not found

Make sure nvm is installed and available in the integrated terminal used by VS Code.

中文

Node Version Runner 是一个 VS Code 插件，用于按照当前工作区要求的 Node.js 版本运行 package.json 中的脚本。

插件会读取工作区根目录的 package.json，让你从 Quick Pick 列表里选择脚本，然后自动切换 Node.js 版本，并在 VS Code 终端中运行该脚本。

nvm use <version> && npm run <script>

功能

• 从当前工作区根目录的 package.json 读取 npm scripts。
• 通过命令面板执行 Node Version Runner: Run npm Script。
• 在 VS Code 底部状态栏显示常驻的 Node Script 按钮。
• 支持 npm、pnpm、yarn。
• 支持从常见项目配置文件中自动识别 Node.js 版本。

Node 版本识别顺序

Node.js 版本按以下顺序解析：

1. nodeVersionRunner.nodeVersion 插件设置
2. .nvmrc
3. .node-version
4. package.json 中的 engines.node
5. 14

使用要求

• VS Code 1.85.0 或更高版本。
• 已安装 nvm，并且 VS Code 终端可以访问 nvm 命令。
• 当前打开的工作区根目录存在 package.json。
• package.json 中至少定义了一个 script。

示例：

{
  "scripts": {
    "dev": "vite",
    "build": "vite build"
  }
}

使用方法

1. 在 VS Code 中打开一个 Node.js 项目目录。

2. 打开命令面板：

   Cmd + Shift + P
   

   Windows 或 Linux：

   Ctrl + Shift + P
   

3. 执行：

   Node Version Runner: Run npm Script
   

4. 从列表中选择要运行的脚本。

5. 插件会打开终端，并使用识别到的 Node.js 版本运行该脚本。

你也可以直接点击底部状态栏中的 Node Script 按钮。

插件配置

在 VS Code 设置中搜索 Node Version Runner。

VS Code settings.json 示例：

{
  "nodeVersionRunner.nodeVersion": "18",
  "nodeVersionRunner.packageManager": "pnpm",
  "nodeVersionRunner.showStatusBarButton": true
}

安装到 VS Code

开发调试模式

适合本地开发或调试插件。

1. 用 VS Code 打开这个插件项目目录。
2. 按 F5 启动 Extension Development Host。
3. 在新打开的 VS Code 窗口中打开一个 Node.js 项目。
4. 从命令面板执行 Node Version Runner: Run npm Script，或点击底部状态栏的 Node Script。

这种方式不会把插件永久安装到主 VS Code 窗口中。

VSIX 安装

适合把插件安装到自己的 VS Code 中长期使用。

1. 安装 VS Code 插件打包工具：

   npm install -g @vscode/vsce
   

2. 在插件项目根目录执行打包：

   vsce package
   

3. 安装生成的 .vsix 文件：

   code --install-extension node-version-runner-0.1.0.vsix --force
   

4. 重新加载或重启 VS Code。

也可以通过 VS Code 界面安装：

1. 打开 Extensions 扩展面板。
2. 点击右上角 ...。
3. 选择 Install from VSIX...。
4. 选择生成的 .vsix 文件。

状态栏按钮

插件会在 VS Code 启动完成后自动激活。如果 nodeVersionRunner.showStatusBarButton 开启，底部状态栏会显示 Node Script 按钮。

如果没有看到按钮：

• 确认插件已启用。
• 确认 nodeVersionRunner.showStatusBarButton 为 true。
• 执行 Developer: Reload Window 重新加载窗口。
• 如果你修改过 package.json，需要重新打包并安装最新 .vsix。

Windows 说明

在原生 Windows 中，请先安装 nvm-windows。插件会使用 cmd.exe 作为终端，因此可以执行：

nvm use 14 && npm run serve

在 WSL 中，请在 WSL 环境内安装 Linux/macOS 版本的 nvm。VS Code Remote WSL 会在 Linux 环境中运行插件。

常见问题

没有找到脚本

请确认当前打开的工作区根目录存在 package.json，并且 scripts 不为空。

Node.js 版本不正确

按以下顺序检查版本来源：

1. VS Code 设置 nodeVersionRunner.nodeVersion
2. .nvmrc
3. .node-version
4. package.json 中的 engines.node

提示找不到 nvm

请确认已经安装 nvm，并且 VS Code 集成终端可以正常访问 nvm 命令。