Spring Boot Runner (plugin-free) — VSCode Extension

A VSCode extension that runs an unpackaged Spring Boot (Maven) project straight from the command line via java -cp, without the spring-boot-maven-plugin and without the official VSCode Spring Boot plugin.

It is a thin UI over scripts/run-spring-boot.mjs. One core script, one entry point:

VSCode extension → human clicks a command in the editor.

The runner is pure Node (ESM), so no Python install is required — only a Maven on PATH and a JDK.

Source repository（源码仓库）

Gitee：https://gitee.com/boluoshu/spring-boot-runner （branch master）

git clone https://gitee.com/boluoshu/spring-boot-runner.git

Why

The Spring Boot Dashboard "runs" an app by resolving the @SpringBootApplication main class + classpath, then calling java -cp <classpath> <MainClass>. This extension reproduces that with plain command-line tools (maven-dependency-plugin instead of the IDE's JDT classpath resolver) and never needs spring-boot-maven-plugin. The long classpath is written to a per-project @argfile in the temp dir, so the launched command stays tiny and avoids the Windows CreateProcess command-line length limit.

Commands

| Command | What it does | | --- | --- | | Spring Boot Runner: Run Project | Run with a run configuration from .vscode/launch.json. Asks which one when several exist; falls back to auto-detect when none does. | | Spring Boot Runner: Run with Debug (JDWP) | Same, but launches with JDWP (suspend per configuration) and auto-attaches VSCode's Java debugger, so breakpoints work immediately. | | Spring Boot Runner: Run with Custom Args | Prompt for extra args (e.g. --profiles dev --port 8080), then run. Quote paths with spaces; --java-home here overrides the JDK for this run only. | | Spring Boot Runner: Configure Java Home… | Prompt for a JDK home (validated against bin/java(.exe)) and store it in the chosen run configuration. Empty input clears it. | | Spring Boot Runner: Stop | Stop a running/debugging app: detaches the debugger, kills the Java process tree via the PID file (taskkill /PID … /T /F), and sends Ctrl-C to the terminal as a fallback. | Output runs in a reusable integrated terminal named Spring Boot Runner.

Run/debug configurations — `.vscode/launch.json`

Run/debug configurations live in the project's .vscode/launch.json, under this extension's own debugger type spring-boot-runner. They are ordinary debug configurations, so the same file drives three entry points:

the Run and Debug view (dropdown in the sidebar),
F5 (run with debugger) and Ctrl+F5 (run without debugger),
the Run/Debug Configurations… panel contributed by this extension (an IDEA-style form).

Ctrl+Shift+P → Spring Boot Runner: Run/Debug Configurations… opens the panel: a tree of configurations on the left, the selected configuration's form on the right. There is no settings file to edit by hand for run parameters — the panel is an editor for launch.json.

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "spring-boot-runner",
      "request": "launch",
      "name": "应用程序 1",
      "module": "backend/bonlink-agent",        // empty = auto-detect
      "mainClass": "com.bonlink.PlatformApplication", // empty = auto-detect
      "profiles": "dev",
      "port": "8081",
      "vmArgs": "-Xmx1g -Denv=dev",
      "env": "SPRING_DATASOURCE_URL=jdbc:mysql://localhost/db",
      "javaHome": "D:\\soft\\Java\\jdk-21.0.8+9",
      "skipTests": true
    },
    {
      "type": "spring-boot-runner",
      "request": "attach",                      // runs nothing, only attaches
      "name": "远程 JVM 调试 1",
      "hostName": "10.0.0.5",
      "port": 5005
    }
  ]
}

request: "launch" fields:

Field	Default	Meaning
`module`	`""`	Maven module directory name (empty = auto-detect).
`mainClass`	`""`	Fully-qualified main class (empty = auto-detect from `@SpringBootApplication`).
`programArgs`	`""`	Program arguments, space-separated (quote values containing spaces).
`vmArgs`	`""`	Extra JVM arguments, space-separated.
`profiles`	`""`	`spring.profiles.active`.
`port`	`""`	Override `server.port`.
`workingDir`	`""`	Working directory of the `java` process (empty = the module directory).
`env`	`""`	Extra `KEY=VALUE` env vars, semicolon-separated.
`envFile`	`""`	Path to a `.env` file to load.
`javaHome`	`""`	JDK home for both the Maven build and the launched app (empty = `java` on PATH).
`debugPort`	`"5005"`	JDWP port used when debugging.
`suspend`	`true`	When debugging, suspend the JVM until the debugger attaches.
`jrebel`	`false`	Auto-detect the locally installed JRebel extension and inject `-agentpath:…/jrebel64.dll`.
`force`	`false`	Rebuild even when nothing changed (ignore the build cache).
`clean`	`false`	Run `mvn clean` before building.
`skipTests`	`true`	Skip tests during the build.
`offline`	`false`	Maven offline mode (`-o`).

JRebel (hot reload) without hard-coding a path

Tick 自动检测 JRebel in the panel (or write "jrebel": true in launch.json) and the extension finds the native agent at run time and appends -agentpath:<abs path> to the JVM arguments. This replaces hand-writing

-agentpath:C:\\Users\\me\\.vscode\\extensions\\jrebelbyperforcesoftware.jrebel-2026.3.2\\agent\\jrebel\\lib\\jrebel64.dll

which silently breaks the moment JRebel updates and the version number in the directory name changes (the JVM then refuses to start with Invalid -agentpath argument).

Search order, first hit wins:

springBootRunner.jrebelAgentPath setting — explicit override.
vscode.extensions.all — the host's own list, so the real extensionPath is used.
The host's extensions.json manifest — authoritative identifier.id + version + location, and it works even when JRebel is installed but disabled in this window.
Directory-name scan of the extension folders — last-resort fallback.

Sources 2 and 3 carry a version, so when several JRebel builds are installed the newest wins. The scan never assumes a directory-name shape: the same JRebel is jrebelbyperforcesoftware.jrebel-2026.3.2 in .vscode but jrebelbyperforcesoftware.jrebel-2026.3.2-universal in CodeBuddy.

Notes:

The file picked matches the current platform and CPU arch (jrebel64.dll / libjrebel64.so / libjrebelaarch64.so / libjrebel64.dylib); loading the wrong one makes the JVM fail with a bad-ELF / cannot-load error.
If your vmArgs already contain -agentpath:…jrebel… or -Drebel.home=…, injection is skipped — loading the same native agent twice aborts the JVM. You are told this happened.
rebel.xml is still generated by JRebel's own wizard; this only mounts the agent.
When the run configuration is started and nothing was found, you get a warning with a 设置 agent 路径 action rather than a silent no-op.

Running / stopped state in the panel

A configuration that is currently running shows a green ● before its name and replaces the ▶ / 🐞 pair with a red stop button (■), always visible without hovering. Clicking it kills only that configuration's process tree — other configurations keep running.

The state comes from the per-configuration PID file the runner writes (%TEMP%/spring-boot-runner-<project>-<config>.pid) combined with a liveness check, so the indicator clears itself when the app exits on its own or is killed externally. It is polled every 2 s because process death, unlike a debug session, emits no event we can subscribe to.

request: "attach" fields: hostName (default localhost), port (default 5005), timeout. An attach configuration neither builds nor starts anything — only the debugger is attached, and no extra session is created for this extension.

All string fields accept the usual launch.json variables — ${workspaceFolder}, ${workspaceFolderBasename}, ${userHome}, ${env:NAME} — both when started via F5 (VSCode substitutes them) and when started from the Run/Debug Configurations panel (the extension substitutes them itself).

The file is edited through jsonc edits, so entries of other debuggers (java, node, chrome, …) and any comments you wrote are preserved. Entries whose type is not spring-boot-runner are never touched, and a launch.json that does not parse is reported instead of being overwritten.

Earlier versions stored configurations in .vscode/spring-boot-runner.json and read flat springBootRunner.* settings. Both are no longer read or written — .vscode/launch.json is the single source of truth.

`javaHome` (JDK selection)

javaHome resolves java as <javaHome>/bin/java and exports JAVA_HOME=<javaHome> (plus <javaHome>/bin first on PATH) for every Maven invocation, so mvn install compiles with the same JDK that launches the app — mvn.cmd picks its java via JAVA_HOME. Useful when the integrated terminal's java is the wrong version (e.g. the project needs JDK 21 but PATH has JDK 17).

Three ways to set it:

Panel — Run/Debug Configurations… → the JDK (JAVA_HOME, 留空用 PATH 上的 java) field.
Command — Spring Boot Runner: Configure Java Home… prompts for the path and stores it in a chosen run configuration.
launch.json — write "javaHome": "C:\\Program Files\\Java\\jdk-21" directly.

Activity Bar entry

The extension contributes an Activity Bar container (leaf+play icon, media/activity-icon.svg) named Spring Boot Runner. Clicking it opens a view with one-click links for Run / Debug / Custom Args / Stop.

Note: VSCode renders Activity Bar icons monochrome (theme foreground color) — the colored images/icon.png only shows in the Extensions panel, never in the Activity Bar. The top-level icon field and the Activity Bar icon are two independent mechanisms.

Settings

Only three installation-level settings remain; everything that describes a run lives in launch.json. Set via the Settings UI or .vscode/settings.json:

Key	Default	Meaning
`springBootRunner.nodePath`	`""`	Node.js interpreter for `run-spring-boot.mjs` (empty = `node` on PATH). Set an absolute path only if `node` is not resolvable from the integrated terminal.
`springBootRunner.runnerScript`	`null`	Path to `run-spring-boot.mjs` (defaults to the bundled copy under `scripts/`).
`springBootRunner.jrebelAgentPath`	`""`	Override for the JRebel native agent path. Leave empty — auto-detection covers the normal cases; use this only when JRebel lives somewhere the search cannot reach. Supports `${userHome}`.

How Stop works

On start, run-spring-boot.mjs writes its PID to %TEMP%/spring-boot-runner-<project>[-<config name>].pid — the configuration-name suffix keeps several run configurations of one project from overwriting each other's PID and @argfile. Stop reads those files and kills the whole process tree (node → cmd.exe → java) with taskkill /PID <pid> /T /F (Windows) / kill -9 <pid> (others). The PID file is removed on exit.

The same cleanup runs when you press the Stop button of a spring-boot-runner debug session, so F5-started apps are stopped from the debug toolbar too.

Build & install (run these yourself)

cd spring-boot-runner-vscode
npm install              # also installs jsonc-parser (used to edit launch.json safely)
npm run compile          # emits dist/extension.js
# To produce a .vsix you can install in VSCode:
npx @vscode/vsce package # needs @vscode/vsce; installs on demand

Then in VSCode: Extensions → … → Install from VSIX…, pick the generated .vsix. For local dev, press F5 in this folder to launch an Extension Development Host.

Spring Boot Runner（免插件）

boluoshu