Launcher
FreeThe Launcher runs what your project can run: dev servers, scripts, console commands, tests. It detects them from package.json, composer.json, Makefile and other files, and you can add your own. Nothing runs by itself. Before the first start in a project the editor shows you the exact command.
What you do here
- See what the editor found in your project and run it: Detected launchers.
- Add your own commands and run files directly: Own launchers.
- Understand when the editor asks first, and take trust back: Trust.
- Work with ⌃R and the start bar, and adjust the settings: Shortcuts and bar.
Layout
- Start bar in the title bar: the chosen launcher with a status dot, ▶ to run (↻ to restart while it runs), ■ to stop and Open in browser once an address shows up.
- Launcher tool window: the sections Detected, Own and Hidden as a list.
- ▶ in the project tree: when you hover a runnable file or a folder with launchers.
Where the output goes
Every run writes into a channel of its own under Problems & Output, tab Output. The channel carries the launcher's name and stays when the run ends. If a program needs input, In terminal moves it into the terminal together with its output so far. More: Output.
Free and Premium
The launcher is free.
Detected launchers Free
When you open a project, the editor reads its files and lists what can be run: npm scripts, Composer scripts, Makefile targets, console commands of Symfony, Shopware and Laravel and much more. Nothing starts until you click.
Where to find it
- The Launcher tool window, section Detected. Open it from its icon in the stripe or with Show launchers in the command palette.
- In the start bar of the title bar: a click on the launcher's name opens the menu of all launchers.
How to do it
- Open a project and the Launcher window.
- Detected lists the launchers, grouped by the file that defines them, such as
package.jsonorcomposer.json. The project's WebDonkey site is listed under WebDonkey. - Hover a row and click Run (▶). A double-click runs it too.
- The output appears under Problems & Output in the Output tab.
- While the launcher runs, stop it with Stop (■) or start it again with Restart (↻).
The list
Every row shows a status dot, the name and the command. The dot is green for Running, grey for Finished and red for Ended with code …. A framework's most important launcher carries the mark main (Main launcher).
At the top of the window:
- Filter launchers: searches names and commands.
- Shield icon (Trusted: click to take it back): only for trusted projects, see Trust.
- + (New launcher…): adds an own launcher.
- Detect again: reads the project once more.
bin/console and artisan unfold. The editor only loads their commands then ("Loading commands…"). If that takes longer than 30 seconds, it gives up.
A row's context menu offers Run or Restart, Stop, Open in browser, Copy command, Copy as own launcher… and Delete (hide). Hidden launchers go to Hidden and come back with Restore.
Sources
What the editor detects is switched per source under Settings › Starter › Sources. All are on by default.
| Source | What belongs to it |
|---|---|
| package.json scripts | npm, pnpm, yarn or bun, whichever the lock file says, including workspaces |
| Frameworks (main launcher and dev URL) | Vite, Next, Nuxt, Astro, SvelteKit, Angular and Tauri: which script is the main one and where it serves |
| composer.json scripts | every script except Composer's own pre and post hooks |
| Symfony, Shopware and Laravel console | bin/console and artisan commands, loaded only when you unfold them, plus Shopware's build and watch scripts |
| Makefile, justfile, Taskfile, deno.json | targets and tasks from these files |
| Python | pyproject scripts, Django's manage.py, FastAPI and Flask apps, run with uv, Poetry or the project's venv |
| Docker Compose, DDEV, Procfile | docker compose up, per service as well, ddev start and launch, every Procfile process |
| Cargo, Go, Gradle, Maven, .NET, Swift, Flutter, Mix | cargo run, go run, gradlew, mvn, dotnet run and the like |
| VS Code tasks and IntelliJ run configurations | taken over where they can be expressed as a command |
| WebDonkey site | starts the site's services in WebDonkey |
Open in browser
When an address shows up in a launcher's output, such as Vite's dev URL, Open in browser appears on the row and in the start bar. A click opens the address in your browser. When you run the WebDonkey site, WebDonkey starts its services, the editor reports "… is running in WebDonkey." and then offers Open in browser for the site.
Troubleshooting
| What you see | Why | What to do |
|---|---|---|
| "Port … is taken by … (PID …)." | Another process already listens on the port | Stop the other process or choose another port |
| "… is missing" | The launcher needs a program that cannot be found on this Mac | Install in WebDonkey, Install with Homebrew or Open download page. Nothing gets installed unless you say so. |
| "Detection is switched off in the settings." | Detect launchers is off | Switch it back on under Settings › Starter |
| "Nothing found to run in this project." | No source found anything | Add an own launcher |
| "WebDonkey is not running." | The WebDonkey site needs WebDonkey running. The editor tried to start it, that did not work. | Start WebDonkey by hand and try again |
See also
Own launchers Free
Anything the editor does not detect by itself you add as an own launcher: a command with arguments, working folder and environment variables, optionally with another launcher that should run first. Single files you can also run directly, without a launcher.
Where to find it
- Right-click a file or folder in the project tree: Add as launcher…
- Right-click the ▶ in the project tree: Add another launcher… (if there is none yet: Add as launcher…)
- Launcher tool window: + (New launcher…)
- Start bar menu and command palette: New launcher…
How to do it
- Right-click a file or folder and choose Add as launcher….
- The Add as launcher dialog comes prefilled: for a file with its name and the matching program, for a folder with the folder as working folder.
- Check the fields and click Save.
- The launcher shows under Own in the launcher window and in the start bar menu.
Fields
| Field | What goes in |
|---|---|
| Name | what the launcher is called in lists and menus |
| Command | the program, such as npm or php |
| Arguments | everything after the program, as in the shell: spaces separate, quotes group. The editor splits the line into single arguments and never runs it as shell text. |
| Working folder (relative to the project) | empty means Project folder |
| Environment variables (KEY=value, one per line) | extra variables for this run |
| .env file | a file with variables, such as .env |
| Start first | another launcher that should run first, or Nothing. If it is running already, the editor does not start it again. |
Folders and files must be inside the project. A project can have up to 200 own launchers.
Edit and delete
- In the launcher window: right-click the row, Edit… or Delete.
- In the project tree: right-click the file or folder, Edit launcher “…”… and Delete launcher “…”. If a folder has several own launchers, they are under Edit launcher and Delete launcher.
If the launcher is still running, the editor asks: "Deleting it stops the running process. Its output stays under “Problems & Output”." Confirm with Stop and delete.
You cannot edit a detected launcher, but Copy as own launcher… turns it into an own one you can change.
Run a file
Right-click a file and Run file, the ▶ in the project tree, or ⌃⇧R for the file in the active tab. The editor takes the program from the shebang line, otherwise from the extension: bash for .sh, php for .php, node for .js, python3 for .py, plus Ruby, Perl, Lua, Go, Swift, Kotlin scripts, R, Julia, PowerShell, Dart, Elixir, AppleScript and more. The file runs from the project folder, with its path relative to it.
Three kinds of file are opened instead of run:
.sqlopens a SQL console in the Database window, with the site's database, otherwise with a running local connection..httpopens WebDonkey's API client. WebDonkey has to be running for that..htmlopens the page in the project's site, otherwise straight in the browser.
What happens in the background
The editor keeps own and hidden launchers in the project under .webdonkey-editor/starters.json. The folder gets a .gitignore of its own so it does not end up in the repository. Own launchers only apply to this project.
Troubleshooting
| What you see | What to do |
|---|---|
| "Give the launcher a name." / "Enter the command to run." | Fill in Name or Command |
| "A quote in the arguments is not closed." | Check the quotes |
| "Variable names may only use letters, digits and _." | Fix the names left of the = |
| "Folders and files must be inside the project." | Choose a folder inside the project |
| "A launcher cannot start itself first." | Under Start first, choose another launcher or Nothing |
| "No program is known for this kind of file." | Add a shebang line or create an own launcher with a command |
| "The working folder does not exist." / "The .env file could not be read." | Fix the path in the dialog |
| "No database connection is available. Start one in WebDonkey first." | Start a database in WebDonkey or add an own connection |
See also
Trust Free
Scripts from a project can do anything you can do on your Mac. That is why the editor asks before the first start in a project and shows you the exact command. Only once you trust the project do its launchers run.
Where to find it
- The dialog appears at the first start of a launcher in a project, also the first time you unfold
bin/consoleorartisan. - Take it back: the shield icon at the top of the launcher window, or the command Stop trusting this project's launchers in the command palette.
- Switch it off: Settings › Starter › Ask before the first start in a project.
The dialog
"Run this project's scripts?" shows:
- the exact command that would run,
- the folder it runs in ("In …"),
- the note that the project counts as trusted afterwards.
You have two ways:
- Trust and run (when starting) or Trust and load (when unfolding the console commands): the project counts as trusted from now on, the command runs.
- Cancel: nothing runs, the project stays untrusted.
Run scripts only if you trust where the project comes from.
Take trust back
- Open the launcher window.
- Click the shield icon at the top (Trusted: click to take it back). It only shows while the project is trusted.
- The editor reports "This project is no longer trusted. The next start asks again."
Stop trusting this project's launchers in the command palette does the same.
Without the question
If you switch off Ask before the first start in a project, the editor silently trusts every project at its first start. That is more convenient, but then a click on ▶ also runs scripts from projects you do not know.
What happens in the background
The list of trusted projects lives on your Mac, per project folder. A folder reached through a symlink counts as the same project. Trust applies to all launchers of the project, own ones and Run file included.
See also
Shortcuts and bar Free
⌃R runs the last launcher again, ⌃⇧R runs the current file. The start bar in the title bar shows the chosen launcher and controls it. Under Settings › Starter you decide what the editor detects and when it asks.
Shortcuts
| Key | Command | What happens |
|---|---|---|
| ⌃R | Run last launcher | runs the launcher you started last, otherwise the one chosen in the start bar |
| ⌃⇧R | Run current file | runs the file in the active tab, see Run a file |
With the cursor in the terminal, ⌃R and ⌃⇧R do not act as launcher shortcuts. ⌃R stays the shell's history search there. The command palette also has Stop launcher (while the last launcher runs), New launcher…, Show launchers and Stop trusting this project's launchers.
Start bar
The start bar sits in the title bar as soon as a project is open and has launchers.
- Name with status dot: a click opens the menu. The Main launcher entries come first, then the others. A click picks a launcher for the bar. At the end of the menu are Run current file, New launcher… and Show launchers.
- ▶ (Run), or ↻ (Restart) while it runs.
- ■ (Stop) while it runs.
- Open in browser once the launcher has reported an address.
Without a choice of your own, the bar shows the main launcher of the project folder, otherwise the first launcher.
Settings
Under Settings › Starter:
| Setting | What it does | Default |
|---|---|---|
| Detect launchers | Reads package.json, composer.json, Makefile and friends when a project opens. Nothing runs by itself. |
on |
| ▶ in the project tree | Shows a run button when hovering a runnable file or a folder with launchers | on |
| Ask before the first start in a project | Shows the exact command once before a project's scripts may run, see Trust | on |
| Sources | one switch per source, see Detected launchers | all on |
The whole launcher is switched off under Features with Launcher: no window, no ▶ in the tree, no detection, no shortcuts.
The ▶ in the project tree
When you hover a file the editor can run, or a folder with launchers, a ▶ appears. A click runs the file or starts the only launcher. If there are several, the click opens a menu; a right-click always opens it. While a launcher of the entry runs, the ▶ shows a green dot instead, after an error a red one.