Uh oh!
There was an error while loading. Please reload this page.
[RFC] feat(nitro): embed observability dashboard in-process at /_workflow - #2548
Merged
Conversation
🦋 Changeset detectedLatest commit: e556071 The changes in this PR will be included in the next version bump. This PR includes changesets to release 16 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
Contributor
Contributor
📊 Benchmark Results
workflow with no steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Nitro | Next.js (Turbopack) workflow with 1 step💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Express | Next.js (Turbopack) workflow with 10 sequential steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Express | Next.js (Turbopack) workflow with 25 sequential steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Next.js (Turbopack) | Express workflow with 50 sequential steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Express | Next.js (Turbopack) Promise.all with 10 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Express | Next.js (Turbopack) Promise.all with 25 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Nitro | Next.js (Turbopack) Promise.all with 50 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Express | Next.js (Turbopack) Promise.race with 10 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Nitro | Next.js (Turbopack) Promise.race with 25 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Express | Next.js (Turbopack) Promise.race with 50 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Nitro | Next.js (Turbopack) workflow with 10 sequential data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Express | Next.js (Turbopack) workflow with 25 sequential data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Express | Next.js (Turbopack) workflow with 50 sequential data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Nitro | Next.js (Turbopack) workflow with 10 concurrent data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Express | Next.js (Turbopack) workflow with 25 concurrent data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Express | Next.js (Turbopack) workflow with 50 concurrent data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Nitro | Next.js (Turbopack) Stream Benchmarks(includes TTFB metrics)workflow with stream💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Nitro | Next.js (Turbopack) stream pipeline with 5 transform steps (1MB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Express | Next.js (Turbopack) 10 parallel streams (1MB each)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Nitro | Next.js (Turbopack) fan-out fan-in 10 streams (1MB each)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Express | Next.js (Turbopack) SummaryFastest Framework by WorldWinner determined by most benchmark wins
Fastest World by FrameworkWinner determined by most benchmark wins
Column Definitions
Worlds:
|
Contributor
🧪 E2E Test Results✅ All tests passed Summary
Details by Category✅ ▲ Vercel Production
✅ 💻 Local Development
✅ 📦 Local Production
✅ 🐘 Local Postgres
✅ 🪟 Windows
✅ 📋 Other
|
pranaygp
marked this pull request as draft
June 20, 2026 21:25
pranaygp
marked this pull request as ready for review
June 21, 2026 21:12
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
Serve the @workflow/web observability UI inside the Nitro process at a configurable route (default /_workflow) instead of spawning a separate web server and 302-redirecting to it. Enabled in dev, omitted from production builds by default (so prod bundles carry no @workflow/web import). Never mounted on Vercel deploys (use the hosted dashboard). - @workflow/web: add a framework-neutral `@workflow/web/handler` (createWorkflowWebHandler) that serves SSR + static client assets + RPC as one Web Request->Response handler under a runtime basename (asset manifest URLs + publicPath are reprefixed so the dashboard is self-contained under its mount). Add `@workflow/web/registry` for embedded-dashboard discovery; make the RPC/stream client basename-aware. - @workflow/nitro: mount the handler in-process (Nitro v2 h3 + v3 native paths), gated by a new `dashboard` option (default = dev). - @workflow/cli: `workflow web` / `inspect --web` defer to a running embedded dashboard instead of starting a redundant server; pass `--standalone` to force the standalone UI. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Address review feedback on the embedded dashboard: - Normalize the dashboard mount path in one place before it feeds both the Nitro route registration (`[path, path + '/**']`) and the handler `basename`. Force a single leading slash, strip trailing slashes, and reject the root mount, so a custom `path` can't make the route and the handler's internal `normalizeBasename` disagree. - Replace the handler-level `!nitro.routing` v2 checks with the existing `isNitroV2()` helper for consistent v2/v3 detection. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
pranaygpforce-pushed
the
pgp/nitro-web-integration
branch
from
June 23, 2026 22:06
4ba2a5a to
c235d1aCompareVaguelySerious
approved these changes
Jun 26, 2026
VaguelySerious
left a comment
Member
There was a problem hiding this comment.
AI review: no blocking issues
Validated locally by building a fresh Nitro v3 app against this PR's tarball and exercising the embedded dashboard end-to-end:
| Check | Result |
|---|---|
/_workflow served in-process (not the old 302 redirect) | 200 text/html |
| Client assets reprefixed under the mount, correct MIME | /_workflow/assets/*.js as text/javascript, no root-namespace leakage |
| RPC routed under the mount | /_workflow/api/rpc hits the handler, not the SPA fallback |
| Deep-link served by the handler | /_workflow/run/<id> → 200 (no SPA-fallback issue) |
| Single port / no orphan | only the app port listens; no second server spawned |
| Embedded handler self-registers | registry entry with url + basename + world + pid |
workflow web defers to the embedded dashboard | detects + opens it, does not spawn a redundant server |
--standalone | bypasses detection, spawns the standalone UI |
Custom dashboard: { path } | remounts (assets follow), default path 404s |
| Live UI | runs render over the same origin |
Changes I'd like (all non-blocking) are inline: docs not updated for the new behavior/option, and the new logic lacks automated coverage. Approving.
| * | ||
| * @default nitro.options.dev | ||
| */ | ||
| dashboard?: boolean | { enabled?: boolean; path?: string }; |
There was a problem hiding this comment.
AI Review: Note
This adds a user-facing dashboard option, but the PR touches no docs. Two updates needed in docs/content/docs/v5/api-reference/workflow-nitro/index.mdx:
- The behavior line still says "Serves a redirect to the local observability dashboard at
/_workflowin development" — now stale; it's served in-process with no redirect. - Add
dashboardto the module-options table (type, defaultnitro.options.dev, configurablepath).
Per repo convention, user-facing changes should be reflected in docs.
| * the root mount (whose `/**` catch-all would swallow the host app), falling | ||
| * back to the default. | ||
| */ | ||
| function normalizeDashboardPath(path: string): string { |
There was a problem hiding this comment.
AI Review: Note
No automated coverage for the new logic. normalizeDashboardPath is a pure function that's cheap to unit-test and has real edge cases worth pinning: trailing slashes, duplicate leading slashes, and the root-mount rejection that falls back to the default (the /** catch-all swallowing the host app is exactly what this guards against). The handler's asset-reprefixing and the CLI registry-detection path are also untested.
I verified all of these manually (in-process serve, asset reprefix, custom path remount, --standalone bypass, embedded detection), but a couple of unit tests would lock the behavior in against regressions.
| signal: AbortSignal.timeout(1500), | ||
| }); | ||
| // Any non-5xx response means something is serving that route. | ||
| if (res.status < 500) live.push(entry); |
There was a problem hiding this comment.
AI Review: Nit
res.status < 500 treats a 404 at the recorded URL as a live dashboard. The pid-liveness check above handles the common stale case, so this is low-risk, but a process that's alive yet no longer serving that exact mount (e.g. the path was reconfigured) would lead the CLI to open a 404. Consider narrowing to < 400 (a 404 means nothing is serving that route).
RihanArfan
approved these changes
Jun 29, 2026
Uh oh!
There was an error while loading. Please reload this page.
Contributor
No backport to This is feature work: it adds a new To override, re-run the Backport to stable workflow manually via |
This was referenced Jul 29, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Context
Using Workflow with a Nitro-based framework (Nitro v2/v3, Nuxt) used to run the local observability UI as a separate process: the dev-only
/_workflowhandler booted the entire@workflow/webExpress server on a random port and 302-redirected to it. That second server, second port, and cross-origin redirect is what this PR eliminates.Now the dashboard is served in-process, on the same origin/port, at a configurable route (default
/_workflow) — no second server, no redirect, no orphan process.This is the first half of making
@workflow/nitroan all-in-one integration. The other half — auto-starting the world on boot — is a follow-up PR that builds on #2544 (ensureWorldStarted) and is intentionally not included here.Changes
@workflow/web— new framework-neutral@workflow/web/handlerexport (createWorkflowWebHandler({ basename })) that serves SSR + static client assets + RPC as a single WebRequest→Responsehandler under a runtime mount path. The React Router build (Vite base/) is reprefixed at runtime — asset-manifest URLs +publicPath— so the dashboard is self-contained under its mount (<basename>/assets/...), never touching the host app's root namespace. Adds@workflow/web/registry(best-effort discovery) and makes the RPC/stream client basename-aware. The standalone@workflow/web/server(CLI at/) is unchanged.@workflow/nitro—addDashboardHandlernow mounts that handler in-process (Nitro v2h3.fromWebHandler+ v3 native paths) instead of redirecting. Newdashboard?: boolean | { enabled?, path? }option; default = on in dev, off in prod. When disabled nothing is registered, so production bundles carry no@workflow/webimport (zero bundle/startup cost). Excluded on Vercel deploys.@workflow/cli—workflow web/inspect --webdetect an already-running embedded dashboard (via the registry, health-checked) and open it instead of spawning a redundant server on:3456.--standaloneforces the standalone UI.Because the embedded data layer shares the host process's
process.env, it reads the same world as the running app automatically (no extra wiring).Test plan
Verified manually across all three targets + prod gating + CLI:
workbench/nitro-v3(v3 native)/_workflow/_workflow/assets/…+ servedtext/javascript, RPCsuccess:trueworkbench/nitro-v2(v2 h3)workbench/nuxt(Vite SSR)/_workflow/run/xserved by the handler (no SPA-fallback issue)/_workflowserves the app's ownindex.html; no@workflow/webin the bundle--standalonebypasses@workflow/web+@workflow/nitrounit tests pass; Biome cleanFollow-up (separate PR, not here)
Auto-start the world on server boot via a Nitro plugin (
ensureWorldStarted), gated off Vercel — depends on #2544 merging first.🤖 Generated with Claude Code