feat(utoopack): restart API server after server rebuilds in dev
- Langage dominant
- TypeScript
- Étoiles
- 23
- Forks
- 6
- Merge moyen
- 10 h 8 min
- PR mergées (30 j)
- 27
Description
## Problem
When `ev dev` uses the default Utoopack adapter, the API server starts after the initial server bundle is emitted, but it is not restarted after an existing server module is rebuilt.
The adapter currently watches the server output only until the first bundle is ready and then closes the watcher. As a result, edits to existing server functions or `src/apis` handlers may be rebuilt by Utoopack while the running Node API process continues serving the previously loaded bundle. Developers need to restart `ev dev` manually.
The framework orchestration layer already exposes `callbacks.onServerBundleReady()` and serializes API process restarts through `restartQueue`; the missing piece is a reliable Utoopack server-rebuild completion signal.
## Proposed behavior
After every successful Utoopack server compilation in development:
1. Refresh the build facts/manifest from the completed output.
2. Call `callbacks.onServerBundleReady()`.
3. Let the existing framework orchestration stop the previous API process and start it from the fresh server entry.
Client-only rebuilds should not restart the API server, and failed or incomplete server compilations should leave the current API process running.
Prefer a compiler/dev-server completion hook exposed by `@utoo/pack`. If no suitable hook is available, continuously watch `dist/server/stats.json` as the completed-build marker, with debouncing and content/version deduplication. Watching arbitrary emitted `.js` files is not sufficient because one compilation can write multiple files.
## Scope
The first implementation can cover source changes inside already-known server entries:
- existing `"use server"` function implementations;
- existing `src/apis` route handlers;
- dependencies reachable from the current server graph.
Adding or removing server functions/routes changes the framework `BuildPlan`. That remains a separate Utoopack dynamic-plan capability gap and may continue to require restarting `ev dev` until lower-level entry/route update APIs are available.
## Acceptance criteria
- The initial server bundle starts the API server exactly once.
- Editing an existing server function restarts the API server after a successful rebuild.
- Editing an existing `src/apis` handler restarts the API server after a successful rebuild.
- Client-only HMR does not restart the API server.
- A failed server compilation does not stop or restart the working API server.
- One server compilation that emits multiple files causes only one restart.
- Rapid rebuilds are serialized/coalesced without port conflicts.
- Closing the dev controller stops the watcher/hook and prevents later callbacks.
- Tests cover initial readiness, repeated rebuilds, failure handling, client-only changes, and cleanup.
## Relevant code
- `packages/bundler-utoopack/src/adapter/index.ts`: initial server-output watcher and Utoopack dev controller.
- `packages/ev/src/_internal/build/commands.ts`: `restartApiServer()`, `restartQueue`, and `handleServerBundleReady()`.
- `packages/ev/src/_internal/build/bundler.ts`: `BundlerDevContext.callbacks.onServerBundleReady` contract.
## Documentation follow-up
Update the CLI documentation so its “API watch” / `node --watch` description matches the implemented lifecycle.
Guide de contribution
Ouvrir le guide de contribution
Évaluation
Cette issue n'a pas encore été évaluée.