Stencil devServer port and openBrowser fail-fast behavior

Dev Server Fail-Fast Behavior

Stencil does not expose a specific configuration option to toggle "fail-fast" mode for port conflicts or browser launch failures. The behavior is tied to the underlying Node.js HTTP server and the open package, meaning there is no stable, documented API to force a non-zero exit code specifically for EADDRINUSE across all versions.

Port Conflicts (EADDRINUSE)

When devServer.port is already occupied, Node.js typically throws an EADDRINUSE error. In most Stencil releases, this results in a non-zero exit code, but this is a side effect of the process crashing rather than a managed configuration feature. Because some versions may handle this differently or log a warning before exiting, you cannot rely on a consistent exit code for automation across different Stencil version ranges.

Headless CI and openBrowser

Setting openBrowser: true in a headless CI environment should not be treated as a hard failure mechanism. Depending on the operating system and the version of the open utility used by Stencil, the result will vary between a logged warning and a silent failure. It does not reliably produce a non-zero exit code that can be used to trigger a CI build failure.

Recommended Implementation for CI

To ensure a stable, fail-fast environment in headless CI, avoid relying on Stencil's internal server logic for environment validation. Instead, use the following strategy:

1. Disable Browser Launch: Set openBrowser: false in stencil.config.ts or via environment overrides to prevent unpredictable OS-level errors.
2. Pre-flight Port Check: Use a shell command to verify the port is clear before starting the server.
3. Process Monitoring: Use a process manager or a simple health-check script to verify the server is responding on the expected port.

# Example: Fail-fast port check before running stencil dev
if lsof -Pi :35729 -sTCP:LISTEN -t >/dev/null ; then
  echo "Error: Port 35729 is already in use"
  exit 1
fi
npm run start

Verification Steps

To confirm the behavior of your specific Stencil version, perform these tests:

• Port Conflict: Start a dummy listener (e.g., nc -l 35729) and run npm run start. Check the exit code using echo $?.
• Headless Test: Run the dev server in a Docker container without a GUI with openBrowser: true and verify if the process remains running despite the lack of a browser.