setupEmulator:<platform> starts dev server implicitly and leaves it running in background

[AshrefRaj]

Description

Running setupEmulator:<platform> automatically starts the development server as part of the command. However, the command completes with exit code 0 while the dev server continues running in the background.

When the command process is terminated, the dev server does not stop. This creates several issues:

• The dev server keeps running silently in the background.
• System resources continue to be consumed.
• The port remains occupied.
• Developers may not realize a server is still running since they did not explicitly start one.
• Killing all node processes does not reliably terminate this process.
• The only way to stop it is by manually identifying the port and killing the process via its PID.

This behavior is confusing because setupEmulator:<platform> appears to finish successfully while leaving behind a long-running background process.

Expected Behavior

• setupEmulator:<platform> should complete all emulator setup tasks and then exit cleanly.
• It should not automatically start the dev server.
• If serving pages locally requires a dev server, the user should be prompted or instructed to start it manually.

Current Behavior

• setupEmulator:<platform> starts the dev server as part of the setup process.
• The command exits successfully but leaves the dev server running in the background.
• The running process is not obvious to the developer and must be manually killed.

Steps to Reproduce

1. Run setupEmulator:<platform>.
2. Wait for the command to finish.
3. Check running processes or the port used by the dev server.
4. Observe that the dev server is still running in the background.

Proposed Solution

Remove the dev server startup from the setupEmulator:<platform> command.

The emulator setup and the dev server should be independent steps:

• setupEmulator:<platform> → performs emulator setup only.
• Developers can manually start the dev server if they want to serve pages locally.

Optionally, the command could display a message such as:

If you want to serve pages locally, please start the dev server using <command>.

Impact

• Prevents hidden background processes.
• Avoids port conflicts.
• Reduces developer confusion.
• Gives developers explicit control over when the dev server runs.

[AshrefRaj]

Opened a PR with the suggested solution.
#205

[mayankmahavar1mg]

Context on the Intentional Behavior

Thanks for raising this and for the detailed write-up!

To give some context on why this behavior was intentionally added:

Why the dev server needs to stay running

The local dev flow requires a running dev server because the WebView inside the emulator/simulator points to your machine's local IP. Without the server up, the app just loads a
blank screen or errors out. We found users were frequently missing this step, then:

1. Realizing the app isn't loading
2. Going back to manually update config.json with the correct local IP
3. Starting the server
4. Re-running setup

A lot of unnecessary back and forth for a step that can be handled automatically.

setupServer is a fallback, not the primary flow

The behavior is intentionally a safety net:

• If npm start is already running on the configured port → server is detected, nothing happens, zero interference
• If the port is unoccupied → server is started in the background as a fallback

The documented flow (updating IP + starting npm start manually) is still the recommended path — we call this out in the
docs. setupEmulator just recovers gracefully when those steps are missed.

Why detached/background is intentional

The server needs to outlive the setupEmulator process because the emulator/simulator stays alive after setup exits and continues to depend on that server. If it were an
attached process, killing the terminal would kill the server and the app would stop loading mid-session.

Scope: local dev only

This only applies when pointing your universal app at a local IP. If you're pointing to a deployed domain, setupServer is effectively a no-op — the port check won't trigger or
interfere with anything.

---

What we can improve

We agree the transparency could be better. We can add a clearer log when the background server is started:

Dev server not detected on port X, starting in background (required for local WebView)

But removing the behavior itself would add friction back for users who miss the manual steps — which is the exact problem this was added to solve.

Happy to discuss further!

[AshrefRaj]

Hi @mayankmahavar1mg ,

Thanks for the feedback regarding friction. I understand the goal of making the setup as seamless as possible for new users.

However, the current implementation that starts a detached background process has several issues:

Concerns with the Current Approach

Resource Leakage
The dev server continues running silently even after setup completes. This leads to unnecessary background resource consumption (CPU/Memory) and potential port conflicts that can be difficult to track.

System Slowdowns
In environments with heavy file monitoring (such as when using agentic tools or IDE formatters), these background processes can cause noticeable performance slowdowns.

Unexpected Behavior
When useHttps is set to true with a remote endpoint (e.g., https://secure-domain.example), starting a local dev server is unnecessary and may create confusion.

---

Proposed Solution:

To balance reducing friction while still giving developers control, I’ve updated the PR with the following approach:

Interactive Shell during setup
The setupEmulator command now includes two optional prompts at the end:

• Would you like to update the local IP in the configuration?
• Would you like to start the dev server?

Both prompts have a 10-second timeout and default to "No".
This ensures that automated scripts or users who prefer a hands-off setup are not blocked, while still offering a quick one-click option for common follow-up actions.

Smart Checks
Before attempting to start the dev server, the command checks whether a server is already running on the configured port.

---

This approach reduces friction for developers who need automation while avoiding unnecessary background processes for those who prefer explicit control.

Looking forward to your thoughts!

[mayankmahavar1mg]

Closing this issue since it is being resolved via #205.

Appreciate the contribution, @AshrefRaj !