Run Package

Run Package provides a JetBrains-style persistent run/debug configuration toolbar for Visual Studio Code. Easily manage, select, and run customized terminal commands and multi-command packs (in parallel or sequentially) with a single click. Run Package provides a JetBrains-style persistent run/debug configuration workflow for Visual Studio Code. Easily manage, select, and run customized terminal commands and multi-command packs (in parallel or sequentially) with a single click.

Key Features

• Persistent Status Bar Controls: Always visible on your bottom status bar:
  • Configuration Dropdown: Displays the active configuration name with its custom icon and chevron.
  • Play (▶) Button: Launches the selected configuration.
  • Stop (■) & Restart (↻) Buttons: Appear dynamically while the configuration is running to give you instant process control.
• Top-Right Editor Toolbar: Matching run/restart/stop action buttons integrated directly into the editor header.
• Bottom Status Bar Configuration Selector:
  • Displays the active configuration name with its custom icon, chevron, and running status ($(sync~spin)).
  • Click anytime to switch configurations, add new commands, build command packs, or edit settings.
• Top-Right Editor Toolbar Controls:
  • Play ($(play)) Button: Standard solid play icon in your editor tab header to run the currently selected configuration.
  • Stop (■) & Restart (↻) Buttons: Dynamically replace the Play button while processes are running, providing instant execution control.
• Single Commands & Command Packs:
  • Single Commands: Run any shell command with custom working directory (cwd), environment variables (env), theme icon, and terminal tab color.
  • Command Packs: Bundle multiple commands together to launch them as a group.
• Execution Modes:
  • Parallel: Spawns all commands simultaneously in their own dedicated named terminals.
  • Sequential: Executes commands one after another. Monitors exit codes and halts the sequence if any step fails.
  • Sequential: Executes commands one after another. Monitors exit codes via VS Code Shell Integration and halts the sequence if any step fails.
• Preserved Terminal Output: Terminal tabs stay open upon completion or failure so you never miss logs or error messages.
• Interactive Configuration Manager: Add, edit, and delete configurations through a fast, keyboard-navigable QuickPick interface.
• Schema Autocomplete & Backwards Compatibility: Full IntelliSense support for .vscode/run-package.json with seamless fallback for .vscode/universal-runner.json.

Quick Start

1. Open the Configuration Menu:
   • Click $(play-circle) Select Config in the status bar, or press Ctrl+Shift+P / Cmd+Shift+P and type Run Package: Select Configuration.
   • Click $(play-circle) Select Config in the bottom status bar, or press Ctrl+Shift+P / Cmd+Shift+P and run Run Package: Select Configuration.
2. Add a Command:
   • Select Add Command, enter your shell command (e.g. npm run dev), name, and optional working directory.
3. Run with One Click:
   • Click the Play (▶) button on the status bar or editor header to start!
   • Click the Play ($(play)) button on the top-right editor tab header to start running!

Configuration Example

Configurations are stored in .vscode/run-package.json (or .vscode/universal-runner.json):

{
  "$schema": "https://raw.githubusercontent.com/SupawishHanmontree/run-package/main/resources/run-package.schema.json",
  "commands": [
    {
      "id": "backend",
      "name": "Backend API",
      "command": "npm run dev",
      "cwd": "server",
      "env": {
        "PORT": "3000"
      },
      "icon": "server",
      "color": "terminal.ansiGreen"
    },
    {
      "id": "frontend",
      "name": "Frontend Web",
      "command": "npm run dev",
      "cwd": "client",
      "icon": "globe",
      "color": "terminal.ansiBlue"
    },
    {
      "id": "test",
      "name": "Run Unit Tests",
      "command": "npm test",
      "icon": "beaker",
      "color": "terminal.ansiYellow"
    }
  ],
  "packs": [
    {
      "id": "dev-all",
      "name": "Full Stack Dev",
      "mode": "parallel",
      "commands": [
        "backend",
        "frontend"
      ]
    },
    {
      "id": "ci-pipeline",
      "name": "Test & Build Pipeline",
      "mode": "sequential",
      "commands": [
        "test",
        "backend"
      ]
    }
  ]
}

Configuration Reference

Command Properties

Pack Properties

Available Commands

Note: Legacy universalRunner.* command identifiers remain registered as aliases for backward compatibility with existing shortcuts.

Troubleshooting & FAQ

Where are my configurations saved?

Configurations are stored in your workspace under .vscode/run-package.json. If you previously used .vscode/universal-runner.json, Run Package detects and reads it automatically.

Can I run commands in a subfolder of a monorepo?

Yes! Set "cwd": "path/to/subfolder" in the command definition. The path will be resolved relative to your workspace root.

How does sequential execution detect when a step finishes?

Run Package leverages VS Code's Terminal Shell Integration API (window.onDidEndTerminalShellExecution) to accurately read exit codes without closing your terminal tab.

License

MIT