Composer, Node, npm und Yarn in PhpStorm sauber integrieren

1. Package-Manager in der IDE – was das bringt

Die Integration von Composer, npm und Yarn in PhpStorm geht über Komfort hinaus: Wer Autocompletion für composer.json nutzt, schreibt keine fehlerhaften Package-Namen und versteht sofort, welche Versionsconstraints zulässig sind. Wer Composer-Scripts als Run-Configuration speichert, kann sie mit einem Klick oder einem Shortcut ausführen, statt im Terminal den Befehl neu zu tippen. Wer npm-Scripts in PhpStorm verwaltet, kann sie debuggen – das geht im reinen Terminal nicht.

In Magento-Projekten mit einem Docker-Setup wie dem von Mark Shust ist die Integration besonders wichtig: Composer läuft im Container, nicht lokal. PhpStorm unterstützt Docker-basierte Interpreter für Composer, sodass alle IDE-Features – Autocompletion, Navigation in Vendor-Pakete, Quick-Documentation für Bibliotheken – mit der im Container installierten PHP-Version und den dort vorhandenen Paketen arbeiten. Das vermeidet den klassischen Fehler, bei dem die IDE mit einer lokalen PHP-Version analysiert, die sich von der Container-Version unterscheidet.

Dieser Artikel zeigt die vollständige Konfiguration für Composer (lokal und Docker-basiert), Node.js mit npm und Yarn, Script-Runner-Integration und die Autocompletion-Features für Konfigurationsdateien.

2. Composer in PhpStorm konfigurieren

Die Composer-Konfiguration in PhpStorm ist unter "Settings > PHP > Composer" zu finden. Dort wird der Pfad zur composer.phar oder zur systemweit installierten composer-Binary angegeben. PhpStorm zeigt die erkannte Composer-Version und validiert den Pfad. Wenn ein PHP-Interpreter konfiguriert ist, wird automatisch geprüft, ob Composer mit dieser PHP-Version kompatibel ist.

Wichtig ist die Option "Synchronize IDE settings with composer.json": Wenn aktiviert, aktualisiert PhpStorm automatisch die Test-Frameworks, Code-Qualitäts-Tools und andere IDE-Einstellungen, sobald composer.json geändert wird. Bei einem Projektstart bedeutet das: composer install ausführen, PhpStorm neu starten – alle Abhängigkeiten sind indiziert und navigierbar, ohne manuelle Konfiguration der einzelnen Tools.

Für die Indizierung von Vendor-Paketen ist es entscheidend, dass das vendor-Verzeichnis nicht als "Excluded" markiert ist. In PhpStorm ist vendor standardmäßig als Library-Root markiert (erkennbar am Stack-Icon im Project-Tree) – das bedeutet: indiziert und navigierbar, aber nicht im "Jump to Class"-Dialog gleichrangig mit eigenem Code. Diese Unterscheidung ist korrekt und gewünscht.

{
  "name": "mironsoft/magento2-extension",
  "description": "Custom Magento 2 extension",
  "type": "magento2-module",
  "require": {
    "php": ">=8.4",
    "magento/framework": ">=2.4.8"
  },
  "require-dev": {
    "phpunit/phpunit": "^11.0",
    "phpstan/phpstan": "^1.12",
    "squizlabs/php_codesniffer": "^3.10"
  },
  "scripts": {
    "test": "phpunit --configuration phpunit.xml",
    "analyse": "phpstan analyse --level=8 src/",
    "cs-check": "phpcs --standard=PSR12 src/",
    "cs-fix": "phpcbf --standard=PSR12 src/"
  },
  "autoload": {
    "psr-4": {
      "Mironsoft\\Extension\\": "src/"
    }
  }
}
// PhpStorm: Ctrl+Click on "phpunit/phpunit" -> navigate to vendor/phpunit/phpunit
// PhpStorm: Hover over "^11.0" -> tooltip shows installed version
// PhpStorm: scripts section -> run icon appears next to each script

3. Composer Scripts direkt aus PhpStorm starten

In PhpStorm erscheint neben jedem Eintrag im scripts-Abschnitt der composer.json ein grüner Ausführen-Pfeil. Ein Klick darauf startet den Script direkt – ohne Terminalfokus, ohne Befehl eintippen. Das Ergebnis erscheint im Run-Panel von PhpStorm mit vollständiger Ausgabe. Fehler werden hervorgehoben und können, wenn es sich um PHP-Fehler handelt, direkt über Ctrl+Click zur betreffenden Datei navigiert werden.

Häufig genutzte Scripts lassen sich als permanente Run Configurations speichern: "Run > Edit Configurations > Add > npm/Composer Script". Diese Configurations erscheinen in der Run-Dropdown-Liste oben rechts und können per Shift+F10 gestartet werden. Das ist besonders nützlich für Scripts, die mehrfach täglich ausgeführt werden – etwa PHPStan-Analyse oder PHPUnit-Tests vor einem Commit.

PhpStorm unterstützt auch "Before Launch"-Aktionen in Run Configurations: Ein Test-Run kann so konfiguriert sein, dass zuerst ein Composer-Script ausgeführt wird – etwa zur Code-Generierung oder zur Cache-Bereinigung. Das repliziert CI-Pipelines lokal und stellt sicher, dass Tests unter denselben Vorbedingungen laufen wie in der CI.

4. Node.js und npm/Yarn in PhpStorm einrichten

Die Node.js-Konfiguration findet sich unter "Settings > Languages & Frameworks > Node.js". PhpStorm erkennt lokale Node.js-Installationen automatisch (via PATH) und zeigt verfügbare Versionen. Wenn nvm verwendet wird, muss PhpStorm den nvm-Pfad kennen – das geschieht entweder über die Shell-Konfiguration oder durch explizite Angabe des nvm-Verzeichnisses in den Einstellungen.

Yarn wird unter "Settings > Languages & Frameworks > Node.js > Package manager" konfiguriert: statt npm kann dort Yarn (Classic oder Berry) ausgewählt werden. PhpStorm passt alle internen Operationen entsprechend an – Pakete installieren, Scripts starten und die GUI-Integration des Package-Panels. Wenn das Projekt eine .npmrc oder .yarnrc.yml enthält, liest PhpStorm diese automatisch ein und berücksichtigt Registry-Konfigurationen.

Für Projekte mit mehreren package.json-Dateien (typisch in Magento-Themes mit Tailwind CSS) erkennt PhpStorm alle package.json-Dateien im Projektbaum und erlaubt es, Scripts aus jeder dieser Dateien direkt zu starten. Das ist wichtig für Projekte, bei denen das Frontend-Build-System (z.B. Tailwind-Compiler) im Theme-Verzeichnis liegt und nicht im Projekt-Root.

// package.json in src/app/design/frontend/Mironsoft/default/web/tailwind/
{
  "name": "mironsoft-default-theme",
  "version": "1.0.0",
  "scripts": {
    "build": "tailwindcss -i ./src/tailwind.css -o ../css/styles.css --minify",
    "watch": "tailwindcss -i ./src/tailwind.css -o ../css/styles.css --watch",
    "dev": "tailwindcss -i ./src/tailwind.css -o ../css/styles.css"
  },
  "devDependencies": {
    "tailwindcss": "^4.0.0",
    "@tailwindcss/cli": "^4.0.0"
  }
}

// PhpStorm: npm panel shows all scripts from this package.json
// Double-click "build" -> runs in Run panel with output
// Double-click "watch" -> long-running process with live output
// Green run icon appears next to each script in the editor
// Run Configuration: save "watch" as persistent config -> Shift+F10 to restart

5. npm/Yarn Scripts als Run-Configurations nutzen

Das npm-Panel in PhpStorm (View > Tool Windows > npm) listet alle Scripts aus allen package.json-Dateien im Projekt. Ein Doppelklick auf einen Script-Namen führt ihn aus. Für Scripts die regelmäßig gestartet werden, lohnt es sich, eine Run Configuration anzulegen: "Run > Edit Configurations > Add > npm". Dort kann man Script-Name, Working Directory und Umgebungsvariablen konfigurieren.

Für den watch-Script (der dauerhaft läuft) ist PhpStorm besonders komfortabel: Der laufende Prozess erscheint in einem eigenen Tab im Run-Panel, kann jederzeit neu gestartet oder gestoppt werden, und der Output scrollt live mit. Anders als im Terminal bleibt PhpStorm dabei bedienbar – der Watch-Prozess läuft im Hintergrund während man weiter im Editor arbeitet.

PhpStorm unterstützt auch das gleichzeitige Starten mehrerer Run Configurations über "Compound Configurations": Eine Compound Configuration kann den Tailwind-Watch, einen PHP-Built-in-Server und einen XDebug-Listener gleichzeitig starten – mit einem einzigen Klick oder Shortcut. Das simuliert einen vollständigen Entwicklungsstack direkt aus der IDE.

6. Package-Manager über Docker-Interpreter nutzen

In Docker-basierten Setups wie dem Mark-Shust-Stack für Magento läuft PHP im Container, und damit auch Composer. PhpStorm unterstützt Docker-basierte Composer-Interpreter: Unter "Settings > PHP > Composer" kann als Interpreter ein Docker-Container ausgewählt werden. PhpStorm startet beim Ausführen von Composer-Befehlen automatisch ein Docker-Exec in den konfigurierten Container.

Die Konfiguration erfordert, dass der Docker-Interpreter unter "Settings > PHP > CLI Interpreter" bereits eingerichtet ist (mit dem richtigen Container-Image und Service-Namen aus der docker-compose.yml). Ist das der Fall, übernimmt PhpStorm Composer-Befehle nahtlos: composer require vendor/package aus dem IDE-Dialog wird als docker exec -it phpfpm composer require vendor/package ausgeführt, ohne dass der Entwickler das Terminal öffnen muss.

Für Node.js und npm in Docker ist die Integration etwas anders: PhpStorm hat keine native Docker-Node.js-Interpreter-Konfiguration wie bei PHP. Hier empfiehlt es sich, ein Terminal-Tool einzurichten (Settings > Tools > Terminal: Shell Path auf ein Wrapper-Script setzen, das automatisch docker exec ausführt). Alternativ bleibt das Terminal für npm/Yarn-Befehle offen, während Composer vollständig in der IDE-GUI abgewickelt wird.

// PhpStorm Docker Composer setup (Mark Shust stack)
// Settings > PHP > CLI Interpreter > Add > Docker Compose
//   Service: phpfpm
//   Image: magento-phpfpm:8.4
//   Lifecycle: Connect to existing container

// Settings > PHP > Composer
//   Composer executable: /usr/local/bin/composer (inside container)
//   PHP Interpreter: [Docker: phpfpm] (configured above)

// Now from PhpStorm: Tools > Composer > Manage Dependencies
// PhpStorm runs: docker exec -it phpfpm composer require ...
// Output appears in IDE Run panel

// For Magento bin/composer wrapper — add as External Tool:
// Settings > Tools > External Tools > Add
//   Name: bin/composer
//   Program: $ProjectFileDir$/bin/composer
//   Arguments: $Prompt$
//   Working directory: $ProjectFileDir$

7. Autocompletion für composer.json und package.json

PhpStorm bietet umfangreiche Autocompletion für composer.json: Package-Namen werden mit Vorschlägen aus Packagist ergänzt (bei bestehender Internetverbindung), Versions-Constraints werden validiert, bekannte Schlüssel wie require, autoload und scripts werden mit korrekten Werttypen vorgeschlagen. Hover-Tooltips zeigen die Dokumentation zu Feldern direkt im Editor an.

Für package.json funktioniert dasselbe: Package-Namen aus npm-Registry, Versions-Constraints, bekannte Skript-Befehle und Felder wie main, exports oder browser. Wenn ein Package bereits in node_modules installiert ist, navigiert Ctrl+Click auf den Package-Namen direkt in das Paketverzeichnis – zum Lesen der Quelle oder der installierten Dokumentation.

Ein oft übersehenes Feature: PhpStorm erkennt auch pnpm-workspace.yaml und Yarn-Workspaces und zeigt alle Workspace-Pakete im Completion-Dialog an. Für Monorepos oder Projekte mit mehreren Sub-Packages (wie Magento-Extensions mit einem separaten Frontend-Package) ist das hilfreich, um Workspace-interne Abhängigkeiten korrekt zu referenzieren.

8. Vergleich: Lokale vs. Docker-basierte Interpreter

9. Zusammenfassung

Die Integration von Composer, Node.js, npm und Yarn in PhpStorm eliminiert einen großen Teil der Terminal-Wechsel im Entwicklungsalltag. Composer in PhpStorm bedeutet: Autocompletion für composer.json, Navigation in Vendor-Pakete, Script-Buttons direkt in der Datei und Docker-basierte Ausführung ohne manuelles Exec. npm und Yarn bedeutet: npm-Panel mit allen Scripts, Run Configurations für Watch-Prozesse und Compound Configurations für vollständige Entwicklungsstacks.

Für Docker-basierte Projekte wie Magento mit Mark-Shust-Setup ist die Composer-Docker-Integration besonders wichtig, weil sie sicherstellt, dass PhpStorm mit der korrekten PHP-Version und den Container-Paketen arbeitet. Node.js bleibt in den meisten Fällen lokal installiert, da PhpStorm keinen nativen Docker-Node-Interpreter unterstützt – hier hilft ein Terminal-Wrapper-Script. Das Ergebnis ist ein Entwicklungsworkflow, bei dem der Editor die zentrale Steuerzentrale ist und das Terminal nur für Ausnahmefälle geöffnet wird.

10. FAQ: Composer, Node, npm und Yarn in PhpStorm