New tunnel executor

[tbinna]

The current tunnel executor works, but it leans on a few fragile Nx behaviors and would be more reliable if it were structured differently.

Concrete bug this causes

A nested Forge app build can resolve the wrong outputPath when run under tunnel.

A concrete example from a fictional app:

• the Forge app webpack build is supposed to emit runtime code to dist/apps/example-forge-app/src/index.js
• a clean package run does exactly that
• but when the same build runs under example-forge-app:tunnel, it also emits dist/apps/example-forge-app/index.js at the app root
• during that same tunnel flow, the src/index.js file can stop being the file that gets updated

That is not a Forge requirement issue. It appears to come from leaked Nx task context during nested execution.

The likely mechanism is:

• Nx sets NX_TASK_TARGET_* env vars for the current task
• nx:run-commands passes parent process.env through to child commands
• NxAppWebpackPlugin reads those env vars to decide which target config to merge
• when build is launched from inside tunnel, the webpack plugin can see the outer tunnel target context instead of the inner build target context
• that makes it pick up tunnel.options.outputPath instead of the webpack build output path

So this can cause the runtime bundle to be written to the app root by mistake, even before the forge tunnel subprocess itself becomes relevant.

What feels brittle

The main issue is that tunnel nests several long-running targets within a single executor process in executor.ts. That creates a couple of problems:

• shared process.env gets reused across nested targets, so Nx/webpack task metadata can leak from one child into another
• inferred nx:run-commands targets are especially fragile, because they mostly inherit the parent environment rather than getting a clean executor context
• this does not just affect the final Forge CLI step; it already affects the nested Nx build/watch phase
• the spawned forge tunnel process inherits Nx variables too in async-commands.ts, which is another way unrelated Nx behavior can bleed into the Forge phase
• readiness is based on file presence plus open ports, which works, but it is still coordinating several concurrent systems by side effect rather than by explicit contract

What we could improve

Redesign it around process isolation and explicit orchestration:

• Start each Custom UI as a real child process with a clean env, not a nested runExecutor(...) sharing the parent process.
• Start the Forge app build/watch in its own clean subprocess too.
• Whitelist the env passed to child Nx processes instead of inheriting everything.
• Strip Nx task vars before spawning nested build/watch steps: at minimum NX_BUILD_TARGET, NX_TASK_TARGET_*, WEBPACK_SERVE, and similar executor-specific state.
• Strip the same vars before spawning forge tunnel.
• Treat inferred nx:run-commands as a compatibility path, not the ideal path.
• Prefer explicit executors for Custom UI apps, or at least detect inferred webpack targets and normalize them more defensively.
• Separate “prepare/package” from “serve/watch” orchestration so the control flow is easier to reason about and failures are easier to attribute.

What a better model looks like

Instead of “one executor starts everything and all children inherit the same world”, tunnel could act as an orchestrator that does this:

1. Resolve manifest resources.
2. Start each UI server in its own clean subprocess.
3. Start the Forge app build watch in its own clean subprocess.
4. Run package once.
5. Wait for explicit readiness.
6. Spawn forge tunnel with a scrubbed env.

Similar patterns in the Nx codebase

There are a few Nx patterns that feel like good models for a better tunnel executor.

Best fits

The closest match is the module-federation family.

• module-federation-dev-server.impl.ts separates:
  • start the main app
  • discover/start related apps
  • wait for readiness
  • emit one final “server ready” result
• start-remote-iterators.ts is especially nice because it pulls orchestration into a helper instead of keeping everything inline in the executor.

The other very relevant one is:

• ssr-dev-server.impl.ts

It has the same overall shape as nx-forge:tunnel:

• start multiple targets
• combine iterators
• wait until all required pieces are up
• only then yield ready

That is a good pattern to keep.

Most useful idea

The biggest improvement comes from how Nx sometimes avoids nested executor state entirely.

• build-static-remotes.ts does not rely only on runExecutor(...)
• it forks a fresh nx process and explicitly overrides env, including WEBPACK_SERVE: 'false'

That feels very relevant here, because the tunnel problems are caused by leaked task state like NX_TASK_TARGET_*, NX_BUILD_TARGET, and WEBPACK_SERVE.

So if nx-forge:tunnel needs to:

• start inferred serve targets
• start Forge CLI
• run packaging/build steps concurrently

then borrowing this pattern would help a lot:

• spawn isolated child processes for the risky parts
• scrub/whitelist env for each child
• do not let one nested target mutate shared executor state for the whole process

What I’d copy

From Nx, we could borrow these concrete ideas:

• Use a small orchestration helper like start-remote-iterators.ts for “discover related apps and start them”.
• Keep combineAsyncIterables(...) plus explicit readiness checks, like ssr-dev-server.impl.ts.
• For subprocesses that should not inherit Nx executor state, use a fork/spawn pattern like build-static-remotes.ts.
• Reuse Nx’s process lifecycle ideas from running-tasks.ts: signal forwarding, grouped shutdown, and consistent child cleanup.

How I’d apply it to nx-forge:tunnel

We could keep the high-level flow, but change the boundaries:

1. Discover Custom UI projects from the manifest.
2. Start each Custom UI in an isolated child process, not a shared nested executor context.
3. Start the Forge app build/watch in its own isolated child process.
4. Run package once.
5. Wait for ports/files explicitly.
6. Spawn forge tunnel with a scrubbed env.

One important prioritization point: the Forge subprocess env cleanup is still a good idea, but the nested Nx build isolation is the critical fix for the concrete output-path bug above. The wrong bundle location is already happening during the nested build phase, before the forge tunnel subprocess itself matters.