fix(next): respect basePath for workflow routes#2732
Merged
Conversation
🦋 Changeset detectedLatest commit: ce1ddb2 The changes in this PR will be included in the next version bump. This PR includes changesets to release 21 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: Nitro | Express | 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: Express | Nitro | Next.js (Turbopack) workflow with 50 sequential steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Nitro | 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: Nitro | Express | 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: Express | Nitro | 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: Express | Nitro | Next.js (Turbopack) workflow with 25 sequential data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Nitro | Next.js (Turbopack) workflow with 50 sequential data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Express | Next.js (Turbopack) workflow with 10 concurrent data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Nitro | 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: Nitro | Express | 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: Nitro | Express | 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
|
Contributor
Author
|
CI note: after the force-push rewrite, all checks are green except I reran the canary dev job twice on this PR; it failed the same HMR manifest update test each time ( The first |
Contributor
Author
|
Fresh manual basePath smoke after the rewrite:
The temporary |
Contributor
Author
|
Health-check follow-up pushed in What changed:
Manual health check result from the basePath smoke:
Local proof after the follow-up:
|
3 tasks
…-path-local Signed-off-by: Nathan Colosimo <110621881+NathanColosimo@users.noreply.github.com> # Conflicts: # packages/next/src/index.ts # packages/utils/src/index.ts
VaguelySerious
approved these changes
Jul 6, 2026
VaguelySerious
left a comment
VaguelySerious
left a comment
Member
There was a problem hiding this comment.
AI review: no blocking issues
| | { type: 'webhook'; token: string } | ||
| | { type: 'health' }; | ||
|
|
||
| export function createWorkflowUrl( |
Member
There was a problem hiding this comment.
AI Review: Note
These new URL helpers (createWorkflowUrl, createWorkflowBaseUrl, createWorkflowHealthEndpoint) are the correctness core of this PR but have no dedicated unit test — they're only exercised indirectly via the world-local / world-postgres / builders suites. A focused workflow-routes.test.ts would be worth adding, in particular to pin the subtle property that createWorkflowUrl derives the prefix from the base URL's existing pathname (not the global basePath). That's what keeps the createWorkflowBaseUrl → createWorkflowUrl webhook path from double-prefixing (/v2/v2/...). I verified this holds locally (base URL already carrying /v2 produces a single prefix), but a regression test would lock it in.
| Record<symbol, string | undefined>; | ||
|
|
||
| // Keep this local: @workflow/next is CommonJS, while @workflow/utils is ESM-only. | ||
| function setWorkflowBasePath(basePath: string | undefined): void { |
Member
There was a problem hiding this comment.
AI Review: Nit
This BASE_PATH_SYMBOL + setWorkflowBasePath pair is duplicated from @workflow/utils (the CJS-vs-ESM comment explains why). Both sides depend on the Symbol.for('@workflow/core/basePath') string staying identical — if one drifts, basePath propagation silently breaks with no build/type error. Worth a cross-reference comment on both copies pointing at workflow-routes.ts so the coupling is discoverable.
Contributor
|
Backport PR opened against |
This was referenced Jul 7, 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 free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
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.
Summary
nextConfig.basePath; users should only configurebasePathin Next.jsWORKFLOW_LOCAL_BASE_URLas full overridesFixes #1864.
This is separate from #2729: that PR fixes project-root discovery, while this PR fixes runtime URL/route construction for apps served below a path prefix.
Vercel note
Runtime workflow execution works on a Vercel preview with
basePath: '/v2': direct step calls and async workflow trigger/poll complete through/v2.One platform follow-up remains: the generated Vercel/Next output serves internal workflow invocation at
/v2/.well-known/workflow/v1/flow, but a public direct health probe to/v2/.well-known/workflow/v1/flow?__healthstill hits the app 404 route. That appears to be a Vercel/Next build-output route-table issue, not a Vercel REST API issue and not a Workflow queue/runtime URL issue.Tests
pnpm --filter @workflow/utils --filter @workflow/builders --filter @workflow/core --filter @workflow/world-local --filter @workflow/world-postgres --filter @workflow/next buildpnpm --filter @workflow/utils testpnpm --filter @workflow/next testpnpm exec vitest run packages/world-local/src/config.test.ts packages/world-local/src/queue.test.ts packages/world-postgres/src/queue.test.ts packages/builders/src/constants.test.tspnpm exec biome check --max-diagnostics 12 ...on touched files (passes with existing warnings)git diff --checknextjs-turbopackproduction smoke withbasePath: '/v2': root health 404,/v2health 200, direct step 200, workflow trigger/poll returns133basePath: '/v2': direct step 200, workflow trigger/poll returns133; public/v2health 404 as noted abovegpt-5.5, xhigh): clean after fixing the CommonJS/ESM issue in@workflow/nextxhigh): no blocking findings; requestedclaude-opus-4.8was unavailable