Skip to content

fix(next): respect basePath for workflow routes#2732

Open
NathanColosimo wants to merge 7 commits into
mainfrom
nathanc/fix-next-base-path
Open

fix(next): respect basePath for workflow routes#2732
NathanColosimo wants to merge 7 commits into
mainfrom
nathanc/fix-next-base-path

Conversation

@NathanColosimo

@NathanColosimo NathanColosimo commented Jun 30, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Summary

  • derive Workflow's route prefix from nextConfig.basePath; users should only configure basePath in Next.js
  • pass that basePath into generated workflow entrypoints and route URL construction
  • use shared route helpers for workflow metadata, webhook URLs, manifest/health URLs, and local/postgres queue delivery URLs
  • preserve full URL overrides like WORKFLOW_LOCAL_BASE_URL as full overrides

Fixes #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?__health still 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 build
  • pnpm --filter @workflow/utils test
  • pnpm --filter @workflow/next test
  • pnpm 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.ts
  • pnpm exec biome check --max-diagnostics 12 ... on touched files (passes with existing warnings)
  • git diff --check
  • local nextjs-turbopack production smoke with basePath: '/v2': root health 404, /v2 health 200, direct step 200, workflow trigger/poll returns 133
  • Vercel preview smoke with basePath: '/v2': direct step 200, workflow trigger/poll returns 133; public /v2 health 404 as noted above
  • Codex autoreview (gpt-5.5, xhigh): clean after fixing the CommonJS/ESM issue in @workflow/next
  • Claude Opus fallback review (xhigh): no blocking findings; requested claude-opus-4.8 was unavailable

@changeset-bot

changeset-bot Bot commented Jun 30, 2026 •
edited
Loading

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: e157fba

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 21 packages
Name Type
@workflow/builders Patch
@workflow/core Patch
@workflow/next Patch
@workflow/utils Patch
@workflow/world-local Patch
@workflow/world-postgres Patch
@workflow/astro Patch
@workflow/cli Patch
@workflow/nest Patch
@workflow/nitro Patch
@workflow/rollup Patch
@workflow/sveltekit Patch
@workflow/vite Patch
@workflow/vitest Patch
@workflow/web-shared Patch
@workflow/web Patch
workflow Patch
@workflow/world-testing Patch
@workflow/errors Patch
@workflow/nuxt Patch
@workflow/world-vercel Patch

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

@vercel

vercel Bot commented Jun 30, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
example-nextjs-workflow-turbopack Ready Ready Preview, Comment Jul 2, 2026 10:11pm
example-nextjs-workflow-webpack Ready Ready Preview, Comment Jul 2, 2026 10:11pm
example-workflow Ready Ready Preview, Comment Jul 2, 2026 10:11pm
workbench-astro-workflow Ready Ready Preview, Comment Jul 2, 2026 10:11pm
workbench-express-workflow Ready Ready Preview, Comment Jul 2, 2026 10:11pm
workbench-fastify-workflow Ready Ready Preview, Comment Jul 2, 2026 10:11pm
workbench-hono-workflow Ready Ready Preview, Comment Jul 2, 2026 10:11pm
workbench-nitro-workflow Ready Ready Preview, Comment Jul 2, 2026 10:11pm
workbench-nuxt-workflow Ready Ready Preview, Comment Jul 2, 2026 10:11pm
workbench-sveltekit-workflow Ready Ready Preview, Comment Jul 2, 2026 10:11pm
workbench-tanstack-start-workflow Ready Ready Preview, Comment Jul 2, 2026 10:11pm
workbench-vite-workflow Ready Ready Preview, Comment Jul 2, 2026 10:11pm
workflow-docs Ready Ready Preview, Comment, Open in v0 Jul 2, 2026 10:11pm
workflow-swc-playground Ready Ready Preview, Comment Jul 2, 2026 10:11pm
workflow-tarballs Ready Ready Preview, Comment Jul 2, 2026 10:11pm
workflow-web Ready Ready Preview, Comment Jul 2, 2026 10:11pm

@github-actions

github-actions Bot commented Jun 30, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

📊 Benchmark Results

📈 Comparing against baseline from main branch. Green 🟢 = faster, Red 🔺 = slower.

workflow with no steps

💻 Local Development

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
💻 Local 🥇 Nitro 0.047s (-19.2% 🟢) 1.006s (-1.3%) 0.959s 10 1.00x
💻 Local Express 0.048s (~) 1.005s (~) 0.958s 10 1.03x
💻 Local Next.js (Turbopack) 0.051s (-9.0% 🟢) 1.006s (~) 0.955s 10 1.09x
🐘 Postgres Next.js (Turbopack) 0.065s (+3.7%) 1.012s (~) 0.948s 10 1.38x
🐘 Postgres Express 0.067s (+4.7%) 1.011s (~) 0.944s 10 1.43x
🐘 Postgres Nitro 0.074s (+10.0% 🔺) 1.011s (~) 0.937s 10 1.58x

▲ Production (Vercel)

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
▲ Vercel 🥇 Nitro 0.224s (+24.3% 🔺) 1.656s (+1.8%) 1.432s 10 1.00x
▲ Vercel Express 0.240s (+7.3% 🔺) 1.678s (-5.9% 🟢) 1.438s 10 1.07x
▲ Vercel Next.js (Turbopack) 0.355s (-52.5% 🟢) 2.091s (-15.2% 🟢) 1.736s 10 1.58x

🔍 Observability: Nitro | Express | Next.js (Turbopack)

workflow with 1 step

💻 Local Development

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
💻 Local 🥇 Nitro 1.079s (~) 2.006s (~) 0.927s 10 1.00x
💻 Local Express 1.083s (~) 2.007s (~) 0.924s 10 1.00x
💻 Local Next.js (Turbopack) 1.093s (~) 2.006s (~) 0.912s 10 1.01x
🐘 Postgres Express 1.100s (~) 2.013s (~) 0.913s 10 1.02x
🐘 Postgres Nitro 1.101s (+0.6%) 2.010s (~) 0.909s 10 1.02x
🐘 Postgres Next.js (Turbopack) 1.102s (~) 2.011s (~) 0.909s 10 1.02x

▲ Production (Vercel)

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
▲ Vercel 🥇 Express 1.366s (-7.7% 🟢) 2.881s (-13.8% 🟢) 1.515s 10 1.00x
▲ Vercel Nitro 1.381s (~) 2.785s (-15.8% 🟢) 1.404s 10 1.01x
▲ Vercel Next.js (Turbopack) 2.216s (+7.7% 🔺) 3.990s (+9.8% 🔺) 1.774s 10 1.62x

🔍 Observability: Express | Nitro | Next.js (Turbopack)

workflow with 10 sequential steps

💻 Local Development

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
💻 Local 🥇 Nitro 10.437s (-0.7%) 11.022s (~) 0.586s 3 1.00x
💻 Local Express 10.453s (~) 11.020s (~) 0.567s 3 1.00x
💻 Local Next.js (Turbopack) 10.485s (~) 11.022s (~) 0.537s 3 1.00x
🐘 Postgres Express 10.501s (~) 11.020s (~) 0.519s 3 1.01x
🐘 Postgres Nitro 10.525s (~) 11.017s (~) 0.492s 3 1.01x
🐘 Postgres Next.js (Turbopack) 10.608s (+0.9%) 11.020s (~) 0.412s 3 1.02x

▲ Production (Vercel)

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
▲ Vercel 🥇 Express 11.712s (~) 14.216s (+7.6% 🔺) 2.504s 3 1.00x
▲ Vercel Nitro 11.772s (+1.7%) 13.971s (+9.4% 🔺) 2.199s 3 1.01x
▲ Vercel Next.js (Turbopack) 13.262s (+12.7% 🔺) 14.779s (+6.7% 🔺) 1.517s 3 1.13x

🔍 Observability: Express | Nitro | Next.js (Turbopack)

workflow with 25 sequential steps

💻 Local Development

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
💻 Local 🥇 Nitro 13.599s (~) 14.029s (~) 0.430s 5 1.00x
🐘 Postgres Nitro 13.648s (~) 14.018s (~) 0.370s 5 1.00x
💻 Local Express 13.652s (~) 14.027s (~) 0.374s 5 1.00x
💻 Local Next.js (Turbopack) 13.667s (-0.7%) 14.026s (~) 0.360s 5 1.00x
🐘 Postgres Express 13.734s (~) 14.020s (~) 0.286s 5 1.01x
🐘 Postgres Next.js (Turbopack) 13.747s (~) 14.022s (~) 0.275s 5 1.01x

▲ Production (Vercel)

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
▲ Vercel 🥇 Nitro 16.442s (~) 18.617s (+3.5%) 2.175s 4 1.00x
▲ Vercel Express 16.579s (-1.2%) 18.643s (+0.8%) 2.065s 4 1.01x
▲ Vercel Next.js (Turbopack) 18.436s (+6.0% 🔺) 20.215s (+4.8%) 1.779s 3 1.12x

🔍 Observability: Nitro | Express | Next.js (Turbopack)

workflow with 50 sequential steps

💻 Local Development

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
💻 Local 🥇 Express 12.176s (+0.7%) 13.025s (~) 0.849s 7 1.00x
🐘 Postgres Nitro 12.275s (~) 13.019s (~) 0.744s 7 1.01x
💻 Local Nitro 12.320s (~) 13.027s (~) 0.707s 7 1.01x
💻 Local Next.js (Turbopack) 12.352s (-0.6%) 13.025s (~) 0.674s 7 1.01x
🐘 Postgres Next.js (Turbopack) 12.516s (+0.8%) 13.020s (~) 0.504s 7 1.03x
🐘 Postgres Express 12.519s (+2.3%) 13.019s (~) 0.500s 7 1.03x

▲ Production (Vercel)

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
▲ Vercel 🥇 Nitro 17.906s (-3.4%) 20.328s (+1.4%) 2.422s 5 1.00x
▲ Vercel Express 18.256s (+3.9%) 20.122s (+6.8% 🔺) 1.867s 5 1.02x
▲ Vercel Next.js (Turbopack) 19.918s (+2.4%) 22.209s (+2.8%) 2.291s 5 1.11x

🔍 Observability: Nitro | Express | Next.js (Turbopack)

Promise.all with 10 concurrent steps

💻 Local Development

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
🐘 Postgres 🥇 Nitro 1.174s (-1.3%) 2.007s (~) 0.833s 15 1.00x
🐘 Postgres Express 1.199s (-0.8%) 2.008s (~) 0.809s 15 1.02x
🐘 Postgres Next.js (Turbopack) 1.227s (+2.0%) 2.008s (~) 0.781s 15 1.04x
💻 Local Nitro 1.373s (-2.2%) 2.007s (~) 0.634s 15 1.17x
💻 Local Express 1.426s (+3.3%) 2.006s (~) 0.580s 15 1.21x
💻 Local Next.js (Turbopack) 1.427s (~) 2.006s (~) 0.580s 15 1.21x

▲ Production (Vercel)

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
▲ Vercel 🥇 Nitro 2.085s (-7.2% 🟢) 4.005s (+9.3% 🔺) 1.920s 8 1.00x
▲ Vercel Express 2.505s (+18.6% 🔺) 4.475s (+26.1% 🔺) 1.970s 7 1.20x
▲ Vercel Next.js (Turbopack) 3.912s (+23.8% 🔺) 5.365s (+2.9%) 1.452s 6 1.88x

🔍 Observability: Nitro | Express | Next.js (Turbopack)

Promise.all with 25 concurrent steps

💻 Local Development

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
🐘 Postgres 🥇 Next.js (Turbopack) 1.330s (~) 3.009s (~) 1.679s 10 1.00x
🐘 Postgres Nitro 1.369s (+1.2%) 2.142s (-13.3% 🟢) 0.773s 15 1.03x
🐘 Postgres Express 1.408s (+2.7%) 2.394s (-4.6%) 0.986s 13 1.06x
💻 Local Next.js (Turbopack) 2.263s (-5.4% 🟢) 2.918s (-3.0%) 0.655s 11 1.70x
💻 Local Nitro 2.284s (-5.4% 🟢) 3.009s (~) 0.725s 10 1.72x
💻 Local Express 2.438s (-1.7%) 3.009s (-3.2%) 0.571s 10 1.83x

▲ Production (Vercel)

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
▲ Vercel 🥇 Nitro 2.364s (-2.3%) 4.200s (+11.9% 🔺) 1.835s 8 1.00x
▲ Vercel Express 2.391s (-1.5%) 4.107s (+3.1%) 1.716s 8 1.01x
▲ Vercel Next.js (Turbopack) 4.275s (+24.7% 🔺) 5.993s (+14.1% 🔺) 1.717s 6 1.81x

🔍 Observability: Nitro | Express | Next.js (Turbopack)

Promise.all with 50 concurrent steps

💻 Local Development

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
🐘 Postgres 🥇 Nitro 1.556s (-3.1%) 4.010s (-6.9% 🟢) 2.454s 8 1.00x
🐘 Postgres Express 1.633s (-3.4%) 4.726s (+6.4% 🔺) 3.093s 7 1.05x
🐘 Postgres Next.js (Turbopack) 2.668s (-16.3% 🟢) 6.016s (+2.9%) 3.349s 5 1.71x
💻 Local Express 4.370s (+23.6% 🔺) 5.012s (+6.0% 🔺) 0.642s 6 2.81x
💻 Local Nitro 4.671s (+21.7% 🔺) 5.179s (+12.9% 🔺) 0.508s 6 3.00x
💻 Local Next.js (Turbopack) 4.965s (+31.2% 🔺) 5.512s (+13.2% 🔺) 0.547s 6 3.19x

▲ Production (Vercel)

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
▲ Vercel 🥇 Express 2.636s (-11.4% 🟢) 4.302s (-4.1%) 1.666s 7 1.00x
▲ Vercel Nitro 2.749s (-11.3% 🟢) 4.485s (-5.3% 🟢) 1.735s 7 1.04x
▲ Vercel Next.js (Turbopack) 4.660s (+3.5%) 6.499s (+2.3%) 1.839s 5 1.77x

🔍 Observability: Express | Nitro | Next.js (Turbopack)

Promise.race with 10 concurrent steps

💻 Local Development

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
🐘 Postgres 🥇 Nitro 1.184s (-0.6%) 2.009s (~) 0.824s 15 1.00x
🐘 Postgres Express 1.201s (-2.4%) 2.008s (-3.2%) 0.807s 15 1.01x
🐘 Postgres Next.js (Turbopack) 1.207s (-3.6%) 2.008s (-3.2%) 0.801s 15 1.02x
💻 Local Nitro 1.402s (-2.1%) 2.006s (~) 0.604s 15 1.18x
💻 Local Express 1.431s (~) 2.006s (~) 0.576s 15 1.21x
💻 Local Next.js (Turbopack) 1.444s (-0.8%) 2.007s (~) 0.562s 15 1.22x

▲ Production (Vercel)

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
▲ Vercel 🥇 Nitro 1.977s (-20.3% 🟢) 3.931s (+2.1%) 1.954s 8 1.00x
▲ Vercel Express 1.989s (-6.3% 🟢) 4.032s (+12.4% 🔺) 2.043s 8 1.01x
▲ Vercel Next.js (Turbopack) 3.881s (+14.8% 🔺) 5.477s (+3.2%) 1.596s 6 1.96x

🔍 Observability: Nitro | Express | Next.js (Turbopack)

Promise.race with 25 concurrent steps

💻 Local Development

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
🐘 Postgres 🥇 Next.js (Turbopack) 1.320s (-1.3%) 3.008s (~) 1.688s 10 1.00x
🐘 Postgres Express 1.342s (-1.7%) 2.676s (+3.1%) 1.333s 12 1.02x
🐘 Postgres Nitro 1.344s (+2.0%) 2.507s (+4.8%) 1.164s 12 1.02x
💻 Local Express 2.392s (-2.5%) 3.008s (~) 0.616s 10 1.81x
💻 Local Next.js (Turbopack) 2.491s (-5.5% 🟢) 3.008s (~) 0.517s 10 1.89x
💻 Local Nitro 2.542s (+2.5%) 3.109s (+3.4%) 0.568s 10 1.93x

▲ Production (Vercel)

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
▲ Vercel 🥇 Nitro 2.119s (-9.8% 🟢) 3.924s (+4.0%) 1.805s 8 1.00x
▲ Vercel Express 2.321s (+2.8%) 4.039s (+12.9% 🔺) 1.718s 8 1.10x
▲ Vercel Next.js (Turbopack) 3.690s (+8.8% 🔺) 5.072s (-4.9%) 1.382s 7 1.74x

🔍 Observability: Nitro | Express | Next.js (Turbopack)

Promise.race with 50 concurrent steps

💻 Local Development

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
🐘 Postgres 🥇 Nitro 1.588s (-1.3%) 4.137s (~) 2.549s 8 1.00x
🐘 Postgres Express 1.642s (-0.9%) 4.587s (+6.7% 🔺) 2.944s 7 1.03x
🐘 Postgres Next.js (Turbopack) 2.464s (-25.2% 🟢) 6.216s (~) 3.752s 5 1.55x
💻 Local Express 4.938s (-10.2% 🟢) 6.017s (~) 1.080s 5 3.11x
💻 Local Nitro 5.243s (-7.0% 🟢) 6.015s (~) 0.772s 5 3.30x
💻 Local Next.js (Turbopack) 5.765s (+2.9%) 6.416s (+6.6% 🔺) 0.651s 5 3.63x

▲ Production (Vercel)

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
▲ Vercel 🥇 Nitro 2.724s (-5.0% 🟢) 4.398s (~) 1.674s 7 1.00x
▲ Vercel Express 2.800s (+4.8%) 4.335s (+0.7%) 1.535s 7 1.03x
▲ Vercel Next.js (Turbopack) 4.479s (-10.8% 🟢) 6.156s (-10.0% 🟢) 1.676s 5 1.64x

🔍 Observability: Nitro | Express | Next.js (Turbopack)

workflow with 10 sequential data payload steps (10KB)

💻 Local Development

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
💻 Local 🥇 Nitro 0.566s (-5.7% 🟢) 1.005s (~) 0.439s 60 1.00x
🐘 Postgres Express 0.576s (-4.2%) 1.006s (-1.7%) 0.430s 60 1.02x
🐘 Postgres Nitro 0.587s (~) 1.041s (~) 0.454s 58 1.04x
🐘 Postgres Next.js (Turbopack) 0.602s (+7.0% 🔺) 1.007s (~) 0.404s 60 1.06x
💻 Local Express 0.633s (+11.5% 🔺) 1.039s (+3.4%) 0.406s 58 1.12x
💻 Local Next.js (Turbopack) 0.639s (+1.4%) 1.005s (~) 0.366s 60 1.13x

▲ Production (Vercel)

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
▲ Vercel 🥇 Express 2.402s (-7.4% 🟢) 3.894s (+2.9%) 1.492s 16 1.00x
▲ Vercel Nitro 2.508s (-2.8%) 4.177s (+2.6%) 1.669s 15 1.04x
▲ Vercel Next.js (Turbopack) 3.736s (+9.7% 🔺) 5.494s (+5.6% 🔺) 1.757s 11 1.56x

🔍 Observability: Express | Nitro | Next.js (Turbopack)

workflow with 25 sequential data payload steps (10KB)

💻 Local Development

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
🐘 Postgres 🥇 Nitro 1.345s (-0.7%) 2.029s (+1.1%) 0.685s 45 1.00x
🐘 Postgres Express 1.410s (~) 2.030s (-1.1%) 0.620s 45 1.05x
💻 Local Nitro 1.426s (-6.3% 🟢) 2.006s (~) 0.580s 45 1.06x
🐘 Postgres Next.js (Turbopack) 1.430s (-0.7%) 2.008s (-1.1%) 0.577s 45 1.06x
💻 Local Express 1.470s (-0.7%) 2.006s (-1.1%) 0.536s 45 1.09x
💻 Local Next.js (Turbopack) 1.558s (-5.9% 🟢) 2.006s (-1.1%) 0.449s 45 1.16x

▲ Production (Vercel)

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
▲ Vercel 🥇 Nitro 6.008s (~) 7.881s (+4.2%) 1.872s 12 1.00x
▲ Vercel Express 6.008s (-3.0%) 7.820s (+3.0%) 1.812s 12 1.00x
▲ Vercel Next.js (Turbopack) 8.736s (-3.1%) 10.202s (-8.1% 🟢) 1.466s 9 1.45x

🔍 Observability: Nitro | Express | Next.js (Turbopack)

workflow with 50 sequential data payload steps (10KB)

💻 Local Development

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
🐘 Postgres 🥇 Nitro 2.671s (-1.2%) 3.085s (~) 0.414s 39 1.00x
🐘 Postgres Express 2.756s (+3.6%) 3.059s (+0.8%) 0.303s 40 1.03x
🐘 Postgres Next.js (Turbopack) 2.970s (+7.2% 🔺) 3.372s (+12.1% 🔺) 0.402s 36 1.11x
💻 Local Nitro 3.199s (-1.5%) 3.853s (-3.9%) 0.654s 32 1.20x
💻 Local Express 3.212s (+1.4%) 4.009s (+3.3%) 0.797s 30 1.20x
💻 Local Next.js (Turbopack) 3.325s (-7.3% 🟢) 4.009s (-1.7%) 0.685s 30 1.24x

▲ Production (Vercel)

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
▲ Vercel 🥇 Express 11.255s (-10.3% 🟢) 13.214s (-6.1% 🟢) 1.959s 10 1.00x
▲ Vercel Nitro 11.637s (-2.9%) 13.981s (+4.7%) 2.344s 9 1.03x
▲ Vercel Next.js (Turbopack) 17.787s (+1.6%) 19.471s (-1.8%) 1.684s 7 1.58x

🔍 Observability: Express | Nitro | Next.js (Turbopack)

workflow with 10 concurrent data payload steps (10KB)

💻 Local Development

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
🐘 Postgres 🥇 Next.js (Turbopack) 0.194s (-7.5% 🟢) 1.007s (-1.6%) 0.813s 60 1.00x
🐘 Postgres Nitro 0.226s (+1.7%) 1.006s (~) 0.781s 60 1.16x
🐘 Postgres Express 0.234s (+9.6% 🔺) 1.006s (~) 0.772s 60 1.21x
💻 Local Nitro 0.528s (+5.9% 🔺) 1.005s (~) 0.477s 60 2.72x
💻 Local Express 0.533s (+9.2% 🔺) 1.004s (~) 0.471s 60 2.75x
💻 Local Next.js (Turbopack) 0.651s (~) 1.040s (+1.7%) 0.389s 58 3.36x

▲ Production (Vercel)

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
▲ Vercel 🥇 Nitro 1.035s (+5.2% 🔺) 2.754s (+24.3% 🔺) 1.719s 22 1.00x
▲ Vercel Express 1.095s (+3.6%) 2.738s (+20.2% 🔺) 1.643s 22 1.06x
▲ Vercel Next.js (Turbopack) 2.569s (+28.7% 🔺) 4.021s (+4.2%) 1.451s 16 2.48x

🔍 Observability: Nitro | Express | Next.js (Turbopack)

workflow with 25 concurrent data payload steps (10KB)

💻 Local Development

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
🐘 Postgres 🥇 Nitro 0.341s (+1.8%) 1.006s (~) 0.665s 90 1.00x
🐘 Postgres Express 0.359s (+10.7% 🔺) 1.006s (~) 0.648s 90 1.05x
🐘 Postgres Next.js (Turbopack) 0.363s (+22.4% 🔺) 1.053s (+4.6%) 0.690s 86 1.06x
💻 Local Express 2.486s (+0.5%) 3.009s (~) 0.523s 30 7.29x
💻 Local Nitro 2.500s (-1.9%) 3.009s (~) 0.509s 30 7.33x
💻 Local Next.js (Turbopack) 2.627s (-1.4%) 3.041s (+1.1%) 0.415s 30 7.70x

▲ Production (Vercel)

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
▲ Vercel 🥇 Express 1.352s (+1.9%) 2.905s (+17.5% 🔺) 1.553s 32 1.00x
▲ Vercel Nitro 1.470s (+6.1% 🔺) 3.230s (+17.5% 🔺) 1.761s 28 1.09x
▲ Vercel Next.js (Turbopack) 2.866s (+12.1% 🔺) 4.652s (+9.5% 🔺) 1.786s 20 2.12x

🔍 Observability: Express | Nitro | Next.js (Turbopack)

workflow with 50 concurrent data payload steps (10KB)

💻 Local Development

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
🐘 Postgres 🥇 Nitro 0.601s (+19.0% 🔺) 1.139s (+10.4% 🔺) 0.538s 106 1.00x
🐘 Postgres Express 0.619s (+18.4% 🔺) 1.195s (+10.9% 🔺) 0.577s 101 1.03x
🐘 Postgres Next.js (Turbopack) 0.649s (+21.8% 🔺) 3.171s (+5.3% 🔺) 2.521s 38 1.08x
💻 Local Express 5.559s (-4.4%) 8.490s (-4.4%) 2.932s 15 9.24x
💻 Local Nitro 5.740s (+7.0% 🔺) 8.629s (+3.2%) 2.889s 15 9.54x
💻 Local Next.js (Turbopack) 6.212s (+2.8%) 9.099s (+1.6%) 2.887s 14 10.33x

▲ Production (Vercel)

World Framework Workflow Time Wall Time Overhead Samples vs Fastest
▲ Vercel 🥇 Nitro 1.785s (-1.5%) 3.869s (+13.9% 🔺) 2.085s 32 1.00x
▲ Vercel Express 1.812s (-1.0%) 3.875s (+5.9% 🔺) 2.063s 31 1.02x
▲ Vercel Next.js (Turbopack) 3.957s (-4.4%) 5.748s (-3.5%) 1.791s 21 2.22x

🔍 Observability: Nitro | Express | Next.js (Turbopack)

Stream Benchmarks (includes TTFB metrics)
workflow with stream

💻 Local Development

World Framework Workflow Time TTFB Slurp Wall Time Overhead Samples vs Fastest
💻 Local 🥇 Next.js (Turbopack) 1.146s (~) 1.964s (~) 0.012s (-6.9% 🟢) 2.019s (~) 0.873s 10 1.00x
💻 Local Express 1.154s (~) 2.005s (~) 0.011s (+10.6% 🔺) 2.019s (~) 0.865s 10 1.01x
🐘 Postgres Nitro 1.157s (~) 1.996s (~) 0.001s (-23.1% 🟢) 2.011s (~) 0.854s 10 1.01x
🐘 Postgres Next.js (Turbopack) 1.171s (~) 2.000s (~) 0.001s (+8.3% 🔺) 2.011s (~) 0.840s 10 1.02x
💻 Local Nitro 1.193s (+3.0%) 2.004s (~) 0.010s (-13.3% 🟢) 2.018s (~) 0.825s 10 1.04x
🐘 Postgres Express 1.196s (+3.0%) 1.995s (~) 0.002s (+50.0% 🔺) 2.013s (~) 0.817s 10 1.04x

▲ Production (Vercel)

World Framework Workflow Time TTFB Slurp Wall Time Overhead Samples vs Fastest
▲ Vercel 🥇 Express 1.928s (-11.3% 🟢) 3.420s (~) 1.363s (-27.2% 🟢) 5.314s (-6.9% 🟢) 3.386s 10 1.00x
▲ Vercel Nitro 1.973s (-6.9% 🟢) 3.473s (+9.1% 🔺) 1.374s (-25.8% 🟢) 5.409s (-1.3%) 3.437s 10 1.02x
▲ Vercel Next.js (Turbopack) 3.953s (+16.8% 🔺) 3.938s (-9.8% 🟢) 1.226s (+29.6% 🔺) 6.644s (+0.9%) 2.691s 10 2.05x

🔍 Observability: Express | Nitro | Next.js (Turbopack)

stream pipeline with 5 transform steps (1MB)

💻 Local Development

World Framework Workflow Time TTFB Slurp Wall Time Overhead Samples vs Fastest
🐘 Postgres 🥇 Nitro 1.548s (-1.2%) 2.006s (~) 0.005s (+4.8%) 2.028s (~) 0.480s 30 1.00x
💻 Local Express 1.567s (-1.0%) 2.010s (~) 0.011s (-11.3% 🟢) 2.024s (~) 0.457s 30 1.01x
🐘 Postgres Express 1.587s (~) 2.003s (~) 0.005s (-6.3% 🟢) 2.026s (~) 0.439s 30 1.02x
💻 Local Next.js (Turbopack) 1.588s (-1.5%) 1.969s (~) 0.012s (-11.1% 🟢) 2.025s (~) 0.436s 30 1.03x
💻 Local Nitro 1.605s (+1.8%) 2.041s (+1.6%) 0.011s (-11.6% 🟢) 2.059s (+1.6%) 0.453s 30 1.04x
🐘 Postgres Next.js (Turbopack) 1.680s (-0.6%) 2.011s (-1.6%) 0.005s (-1.9%) 2.027s (-1.6%) 0.347s 30 1.09x

▲ Production (Vercel)

World Framework Workflow Time TTFB Slurp Wall Time Overhead Samples vs Fastest
▲ Vercel 🥇 Express 5.463s (+1.7%) 7.261s (+9.2% 🔺) 0.270s (+19.7% 🔺) 8.037s (+9.3% 🔺) 2.575s 8 1.00x
▲ Vercel Nitro 5.810s (+6.7% 🔺) 7.448s (+13.6% 🔺) 0.293s (+53.4% 🔺) 8.659s (+20.5% 🔺) 2.850s 7 1.06x
▲ Vercel Next.js (Turbopack) 10.084s (+11.0% 🔺) 11.498s (+9.2% 🔺) 0.253s (-7.6% 🟢) 12.220s (+4.0%) 2.136s 5 1.85x

🔍 Observability: Express | Nitro | Next.js (Turbopack)

10 parallel streams (1MB each)

💻 Local Development

World Framework Workflow Time TTFB Slurp Wall Time Overhead Samples vs Fastest
🐘 Postgres 🥇 Nitro 0.795s (+1.9%) 1.061s (~) 0.000s (-100.0% 🟢) 1.080s (-0.7%) 0.286s 56 1.00x
🐘 Postgres Express 0.806s (+3.0%) 1.101s (+4.9%) 0.000s (+Infinity% 🔺) 1.118s (+3.4%) 0.312s 54 1.01x
🐘 Postgres Next.js (Turbopack) 0.980s (+1.2%) 1.395s (-3.1%) 0.000s (-4.7%) 1.404s (-4.2%) 0.424s 43 1.23x
💻 Local Next.js (Turbopack) 1.278s (-4.5%) 1.977s (~) 0.000s (+44.4% 🔺) 2.017s (~) 0.738s 30 1.61x
💻 Local Express 1.327s (-3.9%) 1.919s (-1.6%) 0.000s (+45.3% 🔺) 1.922s (-1.6%) 0.595s 32 1.67x
💻 Local Nitro 1.348s (-2.1%) 1.948s (-1.6%) 0.000s (~) 1.951s (-1.6%) 0.604s 31 1.70x

▲ Production (Vercel)

World Framework Workflow Time TTFB Slurp Wall Time Overhead Samples vs Fastest
▲ Vercel 🥇 Express 2.922s (+1.0%) 4.273s (+5.1% 🔺) 0.000s (+7.7% 🔺) 4.834s (+8.6% 🔺) 1.912s 13 1.00x
▲ Vercel Nitro 3.245s (+6.7% 🔺) 4.945s (+18.5% 🔺) 0.000s (NaN%) 5.529s (+19.9% 🔺) 2.284s 12 1.11x
▲ Vercel Next.js (Turbopack) 5.166s (+6.0% 🔺) 5.488s (-4.5%) 0.000s (~) 6.749s (-1.6%) 1.582s 9 1.77x

🔍 Observability: Express | Nitro | Next.js (Turbopack)

fan-out fan-in 10 streams (1MB each)

💻 Local Development

World Framework Workflow Time TTFB Slurp Wall Time Overhead Samples vs Fastest
🐘 Postgres 🥇 Express 1.764s (-0.6%) 2.305s (-3.8%) 0.000s (-51.9% 🟢) 2.327s (-3.4%) 0.564s 26 1.00x
🐘 Postgres Nitro 1.780s (-3.2%) 2.341s (-1.6%) 0.000s (+Infinity% 🔺) 2.355s (-1.7%) 0.575s 26 1.01x
🐘 Postgres Next.js (Turbopack) 2.933s (+6.7% 🔺) 3.448s (+3.4%) 0.000s (+100.0% 🔺) 3.500s (+4.6%) 0.568s 18 1.66x
💻 Local Express 3.181s (-7.6% 🟢) 3.674s (-8.7% 🟢) 0.001s (+252.9% 🔺) 3.678s (-8.7% 🟢) 0.497s 17 1.80x
💻 Local Nitro 3.377s (+6.3% 🔺) 3.839s (+4.5%) 0.001s (+188.4% 🔺) 3.844s (+4.5%) 0.466s 16 1.91x
💻 Local Next.js (Turbopack) 3.499s (+0.7%) 3.989s (~) 0.001s (+28.6% 🔺) 4.030s (~) 0.531s 15 1.98x

▲ Production (Vercel)

World Framework Workflow Time TTFB Slurp Wall Time Overhead Samples vs Fastest
▲ Vercel 🥇 Express 4.852s (+14.2% 🔺) 5.993s (+14.0% 🔺) 0.000s (NaN%) 6.705s (+18.8% 🔺) 1.853s 9 1.00x
▲ Vercel Nitro 5.247s (+26.4% 🔺) 6.636s (+24.9% 🔺) 0.000s (+22.2% 🔺) 7.366s (+28.6% 🔺) 2.119s 9 1.08x
▲ Vercel Next.js (Turbopack) 7.207s (+0.8%) 7.587s (-5.8% 🟢) 0.000s (-100.0% 🟢) 8.710s (-4.4%) 1.503s 7 1.49x

🔍 Observability: Express | Nitro | Next.js (Turbopack)

Summary

Fastest Framework by World

Winner determined by most benchmark wins

World 🥇 Fastest Framework Wins
💻 Local Nitro 10/21
🐘 Postgres Nitro 13/21
▲ Vercel Nitro 11/21
Fastest World by Framework

Winner determined by most benchmark wins

Framework 🥇 Fastest World Wins
Express 🐘 Postgres 14/21
Next.js (Turbopack) 🐘 Postgres 14/21
Nitro 🐘 Postgres 16/21
Column Definitions
  • Workflow Time: Runtime reported by workflow (completedAt - createdAt) - primary metric
  • TTFB: Time to First Byte - time from workflow start until first stream byte received (stream benchmarks only)
  • Slurp: Time from first byte to complete stream consumption (stream benchmarks only)
  • Wall Time: Total testbench time (trigger workflow + poll for result)
  • Overhead: Testbench overhead (Wall Time - Workflow Time)
  • Samples: Number of benchmark iterations run
  • vs Fastest: How much slower compared to the fastest configuration for this benchmark

Worlds:

  • 💻 Local: In-memory filesystem world (local development)
  • 🐘 Postgres: PostgreSQL database world (local development)
  • ▲ Vercel: Vercel production/preview deployment
  • 🌐 Turso: Community world (local development)
  • 🌐 MongoDB: Community world (local development)
  • 🌐 Redis: Community world (local development)
  • 🌐 Jazz: Community world (local development)
  • 🌐 Redis: Community world (local development)
  • 🌐 Redis + BullMQ: Community world (local development)
  • 🌐 Cloudflare: Community world (local development)
  • 🌐 MySQL: Community world (local development)
  • 🌐 Azure: Community world (local development)
  • 🌐 NATS JetStream: Community world (local development)
  • 🌐 Upstash: Community world (local development)
  • 🌐 Platformatic: Community world (local development)

📋 View full workflow run

@github-actions

github-actions Bot commented Jun 30, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

🧪 E2E Test Results

✅ All tests passed

Summary

Passed Failed Skipped Total
✅ ▲ Vercel Production 1442 0 230 1672
✅ 💻 Local Development 1605 0 219 1824
✅ 📦 Local Production 1605 0 219 1824
✅ 🐘 Local Postgres 1593 0 231 1824
✅ 🪟 Windows 152 0 0 152
✅ 📋 Other 885 0 179 1064
Total 7282 0 1078 8360

Details by Category

✅ ▲ Vercel Production
App Passed Failed Skipped
✅ astro 125 0 27
✅ example 125 0 27
✅ express 125 0 27
✅ fastify 125 0 27
✅ hono 125 0 27
✅ nextjs-turbopack 149 0 3
✅ nextjs-webpack 149 0 3
✅ nitro 125 0 27
✅ nuxt 125 0 27
✅ sveltekit 144 0 8
✅ vite 125 0 27
✅ 💻 Local Development
App Passed Failed Skipped
✅ astro-stable 127 0 25
✅ express-stable 127 0 25
✅ fastify-stable 127 0 25
✅ hono-stable 127 0 25
✅ nextjs-turbopack-canary 133 0 19
✅ nextjs-turbopack-stable 152 0 0
✅ nextjs-webpack-canary 133 0 19
✅ nextjs-webpack-stable 152 0 0
✅ nitro-stable 127 0 25
✅ nuxt-stable 127 0 25
✅ sveltekit-stable 146 0 6
✅ vite-stable 127 0 25
✅ 📦 Local Production
App Passed Failed Skipped
✅ astro-stable 127 0 25
✅ express-stable 127 0 25
✅ fastify-stable 127 0 25
✅ hono-stable 127 0 25
✅ nextjs-turbopack-canary 133 0 19
✅ nextjs-turbopack-stable 152 0 0
✅ nextjs-webpack-canary 133 0 19
✅ nextjs-webpack-stable 152 0 0
✅ nitro-stable 127 0 25
✅ nuxt-stable 127 0 25
✅ sveltekit-stable 146 0 6
✅ vite-stable 127 0 25
✅ 🐘 Local Postgres
App Passed Failed Skipped
✅ astro-stable 126 0 26
✅ express-stable 126 0 26
✅ fastify-stable 126 0 26
✅ hono-stable 126 0 26
✅ nextjs-turbopack-canary 132 0 20
✅ nextjs-turbopack-stable 151 0 1
✅ nextjs-webpack-canary 132 0 20
✅ nextjs-webpack-stable 151 0 1
✅ nitro-stable 126 0 26
✅ nuxt-stable 126 0 26
✅ sveltekit-stable 145 0 7
✅ vite-stable 126 0 26
✅ 🪟 Windows
App Passed Failed Skipped
✅ nextjs-turbopack 152 0 0
✅ 📋 Other
App Passed Failed Skipped
✅ e2e-local-dev-nest-stable 127 0 25
✅ e2e-local-dev-tanstack-start- 127 0 25
✅ e2e-local-postgres-nest-stable 126 0 26
✅ e2e-local-postgres-tanstack-start- 126 0 26
✅ e2e-local-prod-nest-stable 127 0 25
✅ e2e-local-prod-tanstack-start- 127 0 25
✅ e2e-vercel-prod-tanstack-start 125 0 27

📋 View full workflow run

@NathanColosimo NathanColosimo mentioned this pull request Jul 1, 2026
Open
@NathanColosimo

NathanColosimo commented Jul 2, 2026

Copy link
Copy Markdown
Contributor Author

CI note: after the force-push rewrite, all checks are green except E2E Local Dev Tests (nextjs-webpack - canary) and the derived E2E Required Check.

I reran the canary dev job twice on this PR; it failed the same HMR manifest update test each time (should follow Next flow-route HMR rebuild rules for body-only changes). The current main Tests workflow is failing on the same job as well: https://github.com/vercel/workflow/actions/runs/28568531186/job/84700980822

The first nextjs-turbopack - stable dev failure and the Nitro benchmark failure both passed after rerun.

@NathanColosimo

NathanColosimo commented Jul 2, 2026

Copy link
Copy Markdown
Contributor Author

Fresh manual basePath smoke after the rewrite:

  • Temporary workbench config: basePath: '/v2' in workbench/nextjs-turbopack/next.config.ts.
  • Fresh Vercel preview: https://example-nextjs-workflow-turbopack-ixptnm4nf.labs.vercel.dev (dpl_FLpB9FQqLN2qZzU1BBLWiuq6nuAv).
  • Local production smoke from the /v2 build:
    • POST /.well-known/workflow/v1/flow?__health -> 404
    • POST /v2/.well-known/workflow/v1/flow?__health -> 200
    • POST /v2/api/test-direct-step-call -> 200 {"result":5}
    • POST /v2/api/trigger-pages?workflowFn=addTenWorkflow&args=123, then poll /v2/api/trigger-pages?runId=... -> 200 133
  • Vercel preview smoke:
    • POST /.well-known/workflow/v1/flow?__health -> 404
    • POST /v2/.well-known/workflow/v1/flow?__health -> 404 (same public route-table caveat noted in the PR body)
    • POST /v2/api/test-direct-step-call -> 200 {"result":5}
    • POST /v2/api/trigger-pages?workflowFn=addTenWorkflow&args=123, then poll /v2/api/trigger-pages?runId=... -> 200 133

The temporary basePath edit was removed after the smoke; the PR worktree is clean.

@NathanColosimo

NathanColosimo commented Jul 2, 2026

Copy link
Copy Markdown
Contributor Author

Health-check follow-up pushed in 610c9c016.

What changed:

  • Generated workflow route modules now keep the adapter-compatible export const POST = workflowEntrypoint(...) shape and also export GET, HEAD, and OPTIONS as aliases to POST, so withHealthCheck() can actually receive direct health probes in Next App Router.
  • Kept the old public @workflow/utils URL helper exports as wrappers around the new createWorkflowUrl(...) helper, so this stays patch-compatible.
  • Re-ran the basePath queue/probe coverage and restored the utils invalid-basePath coverage.

Manual health check result from the basePath smoke:

  • Local next start with temporary basePath: '/v2' works for /v2/.well-known/workflow/v1/flow?__health using GET, HEAD, OPTIONS, and POST; root /.well-known/... remains 404 as expected.
  • Vercel preview still returns the app 404 for public direct /v2/.well-known/workflow/v1/flow?__health, even though vercel inspect --format=json shows the lambda output exists at v2/.well-known/workflow/v1/flow and other /v2/api/... routes work. That still looks like a Vercel/Next deployed routing issue around basePath + .well-known, not workflow-server and not a missing SDK route file.

Local proof after the follow-up:

  • pnpm --filter @workflow/utils test
  • pnpm --filter @workflow/builders test
  • pnpm --filter @workflow/next test
  • pnpm exec vitest run packages/world-local/src/config.test.ts packages/world-local/src/queue.test.ts packages/world-postgres/src/queue.test.ts
  • pnpm --filter @workflow/utils --filter @workflow/builders --filter @workflow/core --filter @workflow/world-local --filter @workflow/world-postgres --filter @workflow/next build
  • Autoreview panel clean: Codex gpt-5.5 xhigh + Claude claude-opus-4-8 xhigh, 0 findings.

@NathanColosimo NathanColosimo mentioned this pull request Jul 3, 2026
Draft
3 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@ijjk ijjk Awaiting requested review from ijjk ijjk is a code owner

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Workflow does not work well/properly when using basePath on Nextjs app

1 participant

@NathanColosimo