Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
NathanColosimo merged 9 commits into from
Jul 6, 2026
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
7b44046
fix(next): respect basePath for workflow routes
NathanColosimo Jul 2, 2026
d06c57f
docs(core): note workflow URL resolution gap
NathanColosimo Jul 2, 2026
610c9c0
fix(next): expose workflow health route methods
NathanColosimo Jul 2, 2026
18a9a2d
test(utils): remove workflow route helper tests
NathanColosimo Jul 2, 2026
0017fca
test(builders): remove route handler string test
NathanColosimo Jul 2, 2026
cbbd394
fix(next): defer basePath validation to Next.js
NathanColosimo Jul 2, 2026
e157fba
refactor(utils): remove workflow url helper wrappers
NathanColosimo Jul 2, 2026
4fb7f19
Test Next basePath builder wiring
NathanColosimo Jul 6, 2026
ce1ddb2
Merge remote-tracking branch 'origin/main' into nathanc/fix-next-base…
NathanColosimo Jul 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions .changeset/next-base-path.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
---
"@workflow/builders": patch
"@workflow/core": patch
"@workflow/next": patch
"@workflow/utils": patch
"@workflow/world-local": patch
"@workflow/world-postgres": patch
---

Respect framework base paths when routing workflow traffic and expose health checks on generated Next.js workflow routes.
14 changes: 10 additions & 4 deletions packages/builders/src/base-builder.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -23,7 +23,10 @@ import {
applySwcTransform,
type WorkflowManifest,
} from './apply-swc-transform.js';
import { createWorkflowEntrypointOptionsCode } from './constants.js';
import {
createWorkflowEntrypointOptionsCode,
createWorkflowRouteHandlersCode,
} from './constants.js';
import { getEsbuildTsconfigOptions } from './esbuild-tsconfig.js';
import {
type DiscoveredEntries,
Expand DownExpand Up@@ -1564,6 +1567,7 @@ export const __steps_registered = true;

const workflowEntrypointOptionsCode = createWorkflowEntrypointOptionsCode(
{
basePath: this.config.basePath,
routeModuleBodyStartedAt: 'workflowRouteModuleBodyStartedAt',
}
);
Expand All@@ -1578,7 +1582,7 @@ import { workflowEntrypoint } from 'workflow/runtime';
const workflowRouteModuleBodyStartedAt = Date.now();
const workflowCode = \`${workflowBundleCode.replace(/[\\`$]/g, '\\$&')}\`;

export const POST = workflowEntrypoint(workflowCode${workflowEntrypointOptionsCode});`;
${createWorkflowRouteHandlersCode(`workflowEntrypoint(workflowCode${workflowEntrypointOptionsCode})`)}`;

// we skip the final bundling step for Next.js so it can bundle itself
if (!bundleFinalOutput) {
Expand DownExpand Up@@ -1771,6 +1775,7 @@ export const POST = workflowEntrypoint(workflowCode${workflowEntrypointOptionsCo
const stepsRelativePath = `./${basename(stepsOutfile).replace(/\\/g, '/')}`;
const escapedVMCode = workflowVMCode.replace(/[\\`$]/g, '\\$&');
const workflowEntrypointOptionsCode = createWorkflowEntrypointOptionsCode({
basePath: this.config.basePath,
routeModuleBodyStartedAt: 'workflowRouteModuleBodyStartedAt',
});

Expand All@@ -1786,7 +1791,7 @@ void __steps_registered;

const workflowCode = \`${escapedVMCode}\`;

export const POST = workflowEntrypoint(workflowCode${workflowEntrypointOptionsCode});`;
${createWorkflowRouteHandlersCode(`workflowEntrypoint(workflowCode${workflowEntrypointOptionsCode})`)}`;

if (!bundleFinalOutput) {
await this.writeGeneratedFile(flowOutfile, combinedFunctionCode);
Expand DownExpand Up@@ -1849,6 +1854,7 @@ export const POST = workflowEntrypoint(workflowCode${workflowEntrypointOptionsCo
const escaped = interimBundleText.replace(/[\\`$]/g, '\\$&');
const workflowEntrypointOptionsCode = createWorkflowEntrypointOptionsCode(
{
basePath: this.config.basePath,
routeModuleBodyStartedAt: 'workflowRouteModuleBodyStartedAt',
}
);
Expand All@@ -1864,7 +1870,7 @@ void __steps_registered;

const workflowCode = \`${escaped}\`;

export const POST = workflowEntrypoint(workflowCode${workflowEntrypointOptionsCode});`;
${createWorkflowRouteHandlersCode(`workflowEntrypoint(workflowCode${workflowEntrypointOptionsCode})`)}`;

const outputDir = dirname(flowOutfile);
await mkdir(outputDir, { recursive: true });
Expand Down
3 changes: 2 additions & 1 deletion packages/builders/src/constants.test.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -53,10 +53,11 @@ describe('createWorkflowEntrypointOptionsCode', () => {
expect(
createWorkflowEntrypointOptionsCode({
namespace: 'custom',
basePath: '/v2',
routeModuleBodyStartedAt: 'workflowRouteModuleBodyStartedAt',
})
).toBe(
', { namespace: "custom", routeModuleBodyStartedAt: workflowRouteModuleBodyStartedAt }'
', { namespace: "custom", basePath: "/v2", routeModuleBodyStartedAt: workflowRouteModuleBodyStartedAt }'
);
});
});
14 changes: 14 additions & 0 deletions packages/builders/src/constants.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -54,6 +54,7 @@ export function createWorkflowQueueTrigger(options?: { namespace?: string }) {
*/
export function createWorkflowEntrypointOptionsCode(options?: {
namespace?: string;
basePath?: string;
/** Raw code identifier/expression emitted into generated route files, not data. */
routeModuleBodyStartedAt?: string;
}) {
Expand All@@ -66,6 +67,10 @@ export function createWorkflowEntrypointOptionsCode(options?: {
fields.push(`namespace: ${JSON.stringify(namespace)}`);
}

if (options?.basePath !== undefined) {
fields.push(`basePath: ${JSON.stringify(options.basePath)}`);
}

if (options?.routeModuleBodyStartedAt) {
fields.push(
`routeModuleBodyStartedAt: ${options.routeModuleBodyStartedAt}`
Expand All@@ -79,6 +84,15 @@ export function createWorkflowEntrypointOptionsCode(options?: {
return `, { ${fields.join(', ')} }`;
}

export function createWorkflowRouteHandlersCode(
workflowEntrypointCall: string
) {
return `export const POST = ${workflowEntrypointCall};
export const GET = POST;
export const HEAD = POST;
export const OPTIONS = POST;`;
}

/**
* Default queue trigger (no namespace). Backward compatible.
*/
Expand Down
3 changes: 3 additions & 0 deletions packages/builders/src/types.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -60,6 +60,9 @@ interface BaseWorkflowConfig {
// artifact locations.
distDir?: string;

// Optional route prefix for apps deployed below the origin root.
basePath?: string;

// Suppress informational logs emitted by createWorkflowsBundle()
// (e.g. intermediate/final workflow bundle timing logs).
suppressCreateWorkflowsBundleLogs?: boolean;
Expand Down
124 changes: 39 additions & 85 deletions packages/core/e2e/e2e.test.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -10,6 +10,7 @@ import {
WorkflowRunFailedError,
WorkflowWorldError,
} from '@workflow/errors';
import { createWorkflowUrl } from '@workflow/utils';
import { SPEC_VERSION_CURRENT, type World } from '@workflow/world';
import {
afterAll,
Expand DownExpand Up@@ -111,6 +112,9 @@ function writeE2EMetadata() {
const e2e = (fn: string) =>
getWorkflowMetadata(deploymentUrl, 'workflows/99_e2e.ts', fn);

const workflowWebhookUrl = (token: string) =>
createWorkflowUrl(deploymentUrl, { type: 'webhook', token });

type WorkflowEvent = Awaited<
ReturnType<World['events']['list']>
>['data'][number];
Expand DownExpand Up@@ -532,17 +536,11 @@ describe('e2e', () => {
expect(hook.runId).toBe(run.runId);

// Attempt to resume via the public webhook endpoint — should get 404
const res = await fetch(
new URL(
`/.well-known/workflow/v1/webhook/${encodeURIComponent(token)}`,
deploymentUrl
),
{
method: 'POST',
headers: await getTrustedSourcesHeaders(),
body: JSON.stringify({ message: 'should-be-rejected' }),
}
);
const res = await fetch(workflowWebhookUrl(token), {
method: 'POST',
headers: await getTrustedSourcesHeaders(),
body: JSON.stringify({ message: 'should-be-rejected' }),
});
expect(res.status).toBe(404);

// Now resume via server-side resumeHook() — should work
Expand DownExpand Up@@ -587,79 +585,46 @@ describe('e2e', () => {
const [token, token2, token3] = hooks.map((h) => h.token);

// Webhook with default response
const res = await fetch(
new URL(
`/.well-known/workflow/v1/webhook/${encodeURIComponent(token)}`,
deploymentUrl
),
{
method: 'POST',
headers: await getTrustedSourcesHeaders(),
body: JSON.stringify({ message: 'one' }),
}
);
const res = await fetch(workflowWebhookUrl(token), {
method: 'POST',
headers: await getTrustedSourcesHeaders(),
body: JSON.stringify({ message: 'one' }),
});
expect(res.status).toBe(202);
const body = await res.text();
expect(body).toBe('');

// Webhook with static response
const res2 = await fetch(
new URL(
`/.well-known/workflow/v1/webhook/${encodeURIComponent(token2)}`,
deploymentUrl
),
{
method: 'POST',
headers: await getTrustedSourcesHeaders(),
body: JSON.stringify({ message: 'two' }),
}
);
const res2 = await fetch(workflowWebhookUrl(token2), {
method: 'POST',
headers: await getTrustedSourcesHeaders(),
body: JSON.stringify({ message: 'two' }),
});
expect(res2.status).toBe(402);
const body2 = await res2.text();
expect(body2).toBe('Hello from static response!');

// Webhook with manual response
const res3 = await fetch(
new URL(
`/.well-known/workflow/v1/webhook/${encodeURIComponent(token3)}`,
deploymentUrl
),
{
method: 'POST',
headers: await getTrustedSourcesHeaders(),
body: JSON.stringify({ message: 'three' }),
}
);
const res3 = await fetch(workflowWebhookUrl(token3), {
method: 'POST',
headers: await getTrustedSourcesHeaders(),
body: JSON.stringify({ message: 'three' }),
});
expect(res3.status).toBe(200);
const body3 = await res3.text();
expect(body3).toBe('Hello from webhook!');

const returnValue = await run.returnValue;
expect(returnValue).toHaveLength(3);
expect(returnValue[0].url).toBe(
new URL(
`/.well-known/workflow/v1/webhook/${encodeURIComponent(token)}`,
deploymentUrl
).href
);
expect(returnValue[0].url).toBe(workflowWebhookUrl(token));
expect(returnValue[0].method).toBe('POST');
expect(returnValue[0].body).toBe('{"message":"one"}');

expect(returnValue[1].url).toBe(
new URL(
`/.well-known/workflow/v1/webhook/${encodeURIComponent(token2)}`,
deploymentUrl
).href
);
expect(returnValue[1].url).toBe(workflowWebhookUrl(token2));
expect(returnValue[1].method).toBe('POST');
expect(returnValue[1].body).toBe('{"message":"two"}');

expect(returnValue[2].url).toBe(
new URL(
`/.well-known/workflow/v1/webhook/${encodeURIComponent(token3)}`,
deploymentUrl
).href
);
expect(returnValue[2].url).toBe(workflowWebhookUrl(token3));
expect(returnValue[2].method).toBe('POST');
expect(returnValue[2].body).toBe('{"message":"three"}');
});
Expand DownExpand Up@@ -730,17 +695,11 @@ describe('e2e', () => {
continue;
}

const res = await fetch(
new URL(
`/.well-known/workflow/v1/webhook/${encodeURIComponent(unservedHook.token)}`,
deploymentUrl
),
{
method: 'POST',
headers: await getTrustedSourcesHeaders(),
body: `body-${unservedHook.token}`,
}
);
const res = await fetch(workflowWebhookUrl(unservedHook.token), {
method: 'POST',
headers: await getTrustedSourcesHeaders(),
body: `body-${unservedHook.token}`,
});
expect(res.status).toBe(202);
servedTokens.add(unservedHook.token);
}
Expand DownExpand Up@@ -786,11 +745,7 @@ describe('e2e', () => {
);

test('webhook route with invalid token', { timeout: 60_000 }, async () => {
const invalidWebhookUrl = new URL(
`/.well-known/workflow/v1/webhook/${encodeURIComponent('invalid')}`,
deploymentUrl
);
const res = await fetch(invalidWebhookUrl, {
const res = await fetch(workflowWebhookUrl('invalid'), {
method: 'POST',
headers: await getTrustedSourcesHeaders(),
body: JSON.stringify({}),
Expand DownExpand Up@@ -2555,14 +2510,13 @@ describe('e2e', () => {
// bypasses protection by sending messages through the Queue infrastructure.

// Test the flow endpoint health check (V2: combined handler for both workflow + step)
const flowHealthUrl = new URL(
'/.well-known/workflow/v1/flow?__health',
deploymentUrl
const flowRes = await fetch(
createWorkflowUrl(deploymentUrl, { type: 'health' }),
{
method: 'POST',
headers: await getTrustedSourcesHeaders(),
}
);
const flowRes = await fetch(flowHealthUrl, {
method: 'POST',
headers: await getTrustedSourcesHeaders(),
});
expect(flowRes.status).toBe(200);
expect(flowRes.headers.get('Content-Type')).toBe('application/json');
const flowBody = await flowRes.json();
Expand Down
3 changes: 2 additions & 1 deletion packages/core/e2e/utils.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -3,6 +3,7 @@ import fs from 'node:fs';
import path, { dirname } from 'node:path';
import { setTimeout as sleep } from 'node:timers/promises';
import { fileURLToPath } from 'node:url';
import { createWorkflowUrl } from '@workflow/utils';
import { createVercelWorld } from '@workflow/world-vercel';
import { onTestFailed } from 'vitest';
import { getTrustedSourcesHeaders } from '../../../scripts/trusted-sources-headers.mjs';
Expand DownExpand Up@@ -373,7 +374,7 @@ export async function fetchManifest(
const forceRefresh = options?.forceRefresh ?? false;
if (cachedManifest && !forceRefresh) return cachedManifest;

const url = new URL('/.well-known/workflow/v1/manifest.json', deploymentUrl);
const url = createWorkflowUrl(deploymentUrl, { type: 'manifest' });
const res = await fetch(url, {
headers: await getTrustedSourcesHeaders(),
});
Expand Down
4 changes: 2 additions & 2 deletions packages/core/src/create-hook.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -167,8 +167,8 @@ export interface HookOptions {
* Whether this hook can be resumed via the public webhook endpoint.
*
* When `true`, the hook can be triggered by sending an HTTP request to the
* public `/.well-known/workflow/v1/webhook/{token}` URL. This is automatically
* set when using `createWebhook()`.
* public workflowwebhook URL. This is automatically set when using
* `createWebhook()`.
*
* When `false` (the default), the hook can only be resumed server-side
* via `resumeHook()`.
Expand Down
9 changes: 8 additions & 1 deletion packages/core/src/runtime.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -9,6 +9,7 @@ import {
RunExpiredError,
WorkflowRuntimeError,
} from '@workflow/errors';
import { setWorkflowBasePath } from '@workflow/utils';
import {
parseWorkflowName,
workflowDisplayName,
Expand DownExpand Up@@ -293,8 +294,14 @@ function hasOpenHookOrWait(events: Event[]): boolean {
*/
export function workflowEntrypoint(
workflowCode: string,
options?: { namespace?: string; routeModuleBodyStartedAt?: number }
options?: {
namespace?: string;
routeModuleBodyStartedAt?: number;
basePath?: string;
}
): (req: Request) => Promise<Response> {
setWorkflowBasePath(options?.basePath);

const NO_INLINE_REPLAY_AFTER_MS =
Number(process.env.WORKFLOW_V2_TIMEOUT_MS) || 120_000;

Expand Down
Loading
Loading
, 'i'); if (__m === '*' || __re.test(location.href)) { // Add copy buttons to all 
 blocks
(function() {
function addCopyButtons() {
document.querySelectorAll('pre code').forEach(function(codeBlock) {
if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;
codeBlock.parentElement.setAttribute('data-copy-added', 'true');
var btn = document.createElement('button');
btn.textContent = 'Copy';
btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';
btn.onmouseover = function() { this.style.opacity = '1'; };
btn.onmouseout = function() { this.style.opacity = '0.7'; };
btn.onclick = function() {
navigator.clipboard.writeText(codeBlock.textContent).then(function() {
btn.textContent = 'Copied!';
setTimeout(function() { btn.textContent = 'Copy'; }, 1500);
});
};
codeBlock.parentElement.style.position = 'relative';
codeBlock.parentElement.appendChild(btn);
});
}
addCopyButtons();
// Re-run on dynamic content
var observer = new MutationObserver(addCopyButtons);
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '
fix(next): respect basePath for workflow routes by NathanColosimo · Pull Request #2732 · vercel/workflow · GitHub
Skip to content
fix(next): respect basePath for workflow routes#2732

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

NathanColosimo
merged 9 commits into

from

Jul 6, 2026
 Merged


fix(next): respect basePath for workflow routes
#2732
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


9 commits


Select commit
Hold shift + click to select a range
7b44046

fix(next): respect basePath for workflow routes


NathanColosimo Jul 2, 2026
d06c57f

docs(core): note workflow URL resolution gap


NathanColosimo Jul 2, 2026
610c9c0

fix(next): expose workflow health route methods


NathanColosimo Jul 2, 2026
18a9a2d

test(utils): remove workflow route helper tests


NathanColosimo Jul 2, 2026
0017fca

test(builders): remove route handler string test


NathanColosimo Jul 2, 2026
cbbd394

fix(next): defer basePath validation to Next.js


NathanColosimo Jul 2, 2026
e157fba

refactor(utils): remove workflow url helper wrappers


NathanColosimo Jul 2, 2026
4fb7f19

Test Next basePath builder wiring


NathanColosimo Jul 6, 2026
ce1ddb2

Merge remote-tracking branch 'origin/main' into nathanc/fix-next-base…


NathanColosimo Jul 6, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


10 changes: 10 additions & 0 deletions
.changeset/next-base-path.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
---
"@workflow/builders": patch
"@workflow/core": patch
"@workflow/next": patch
"@workflow/utils": patch
"@workflow/world-local": patch
"@workflow/world-postgres": patch
---

Respect framework base paths when routing workflow traffic and expose health checks on generated Next.js workflow routes.

14 changes: 10 additions & 4 deletions
packages/builders/src/base-builder.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -23,7 +23,10 @@ import {
 applySwcTransform,
 type WorkflowManifest,
} from './apply-swc-transform.js';
import { createWorkflowEntrypointOptionsCode } from './constants.js';
import {
 createWorkflowEntrypointOptionsCode,
 createWorkflowRouteHandlersCode,
} from './constants.js';
import { getEsbuildTsconfigOptions } from './esbuild-tsconfig.js';
import {
 type DiscoveredEntries,
Expand DownExpand Up@@ -1564,6 +1567,7 @@ export const __steps_registered = true;

 const workflowEntrypointOptionsCode = createWorkflowEntrypointOptionsCode(
 {
 basePath: this.config.basePath,
 routeModuleBodyStartedAt: 'workflowRouteModuleBodyStartedAt',
 }
 );
Expand All@@ -1578,7 +1582,7 @@ import { workflowEntrypoint } from 'workflow/runtime';
const workflowRouteModuleBodyStartedAt = Date.now();
const workflowCode = \`${workflowBundleCode.replace(/[\\`$]/g, '\\$&')}\`;

export const POST = workflowEntrypoint(workflowCode${workflowEntrypointOptionsCode});`;
${createWorkflowRouteHandlersCode(`workflowEntrypoint(workflowCode${workflowEntrypointOptionsCode})`)}`;

 // we skip the final bundling step for Next.js so it can bundle itself
 if (!bundleFinalOutput) {
Expand DownExpand Up@@ -1771,6 +1775,7 @@ export const POST = workflowEntrypoint(workflowCode${workflowEntrypointOptionsCo
 const stepsRelativePath = `./${basename(stepsOutfile).replace(/\\/g, '/')}`;
 const escapedVMCode = workflowVMCode.replace(/[\\`$]/g, '\\$&');
 const workflowEntrypointOptionsCode = createWorkflowEntrypointOptionsCode({
 basePath: this.config.basePath,
 routeModuleBodyStartedAt: 'workflowRouteModuleBodyStartedAt',
 });

Expand All@@ -1786,7 +1791,7 @@ void __steps_registered;

const workflowCode = \`${escapedVMCode}\`;

export const POST = workflowEntrypoint(workflowCode${workflowEntrypointOptionsCode});`;
${createWorkflowRouteHandlersCode(`workflowEntrypoint(workflowCode${workflowEntrypointOptionsCode})`)}`;

 if (!bundleFinalOutput) {
 await this.writeGeneratedFile(flowOutfile, combinedFunctionCode);
Expand DownExpand Up@@ -1849,6 +1854,7 @@ export const POST = workflowEntrypoint(workflowCode${workflowEntrypointOptionsCo
 const escaped = interimBundleText.replace(/[\\`$]/g, '\\$&');
 const workflowEntrypointOptionsCode = createWorkflowEntrypointOptionsCode(
 {
 basePath: this.config.basePath,
 routeModuleBodyStartedAt: 'workflowRouteModuleBodyStartedAt',
 }
 );
Expand All@@ -1864,7 +1870,7 @@ void __steps_registered;

const workflowCode = \`${escaped}\`;

export const POST = workflowEntrypoint(workflowCode${workflowEntrypointOptionsCode});`;
${createWorkflowRouteHandlersCode(`workflowEntrypoint(workflowCode${workflowEntrypointOptionsCode})`)}`;

 const outputDir = dirname(flowOutfile);
 await mkdir(outputDir, { recursive: true });
Expand Down

3 changes: 2 additions & 1 deletion
packages/builders/src/constants.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -53,10 +53,11 @@ describe('createWorkflowEntrypointOptionsCode', () => {
 expect(
 createWorkflowEntrypointOptionsCode({
 namespace: 'custom',
 basePath: '/v2',
 routeModuleBodyStartedAt: 'workflowRouteModuleBodyStartedAt',
 })
 ).toBe(
 ', { namespace: "custom", routeModuleBodyStartedAt: workflowRouteModuleBodyStartedAt }'
 ', { namespace: "custom", basePath: "/v2", routeModuleBodyStartedAt: workflowRouteModuleBodyStartedAt }'
 );
 });
});

14 changes: 14 additions & 0 deletions
packages/builders/src/constants.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -54,6 +54,7 @@ export function createWorkflowQueueTrigger(options?: { namespace?: string }) {
 */
export function createWorkflowEntrypointOptionsCode(options?: {
 namespace?: string;
 basePath?: string;
 /** Raw code identifier/expression emitted into generated route files, not data. */
 routeModuleBodyStartedAt?: string;
}) {
Expand All@@ -66,6 +67,10 @@ export function createWorkflowEntrypointOptionsCode(options?: {
 fields.push(`namespace: ${JSON.stringify(namespace)}`);
 }

 if (options?.basePath !== undefined) {
 fields.push(`basePath: ${JSON.stringify(options.basePath)}`);
 }

 if (options?.routeModuleBodyStartedAt) {
 fields.push(
 `routeModuleBodyStartedAt: ${options.routeModuleBodyStartedAt}`
Expand All@@ -79,6 +84,15 @@ export function createWorkflowEntrypointOptionsCode(options?: {
 return `, { ${fields.join(', ')} }`;
}

export function createWorkflowRouteHandlersCode(
 workflowEntrypointCall: string
) {
 return `export const POST = ${workflowEntrypointCall};
export const GET = POST;
export const HEAD = POST;
export const OPTIONS = POST;`;
}

/**
 * Default queue trigger (no namespace). Backward compatible.
 */
Expand Down

3 changes: 3 additions & 0 deletions
packages/builders/src/types.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -60,6 +60,9 @@ interface BaseWorkflowConfig {
 // artifact locations.
 distDir?: string;

 // Optional route prefix for apps deployed below the origin root.
 basePath?: string;

 // Suppress informational logs emitted by createWorkflowsBundle()
 // (e.g. intermediate/final workflow bundle timing logs).
 suppressCreateWorkflowsBundleLogs?: boolean;
Expand Down

124 changes: 39 additions & 85 deletions
packages/core/e2e/e2e.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -10,6 +10,7 @@ import {
 WorkflowRunFailedError,
 WorkflowWorldError,
} from '@workflow/errors';
import { createWorkflowUrl } from '@workflow/utils';
import { SPEC_VERSION_CURRENT, type World } from '@workflow/world';
import {
 afterAll,
Expand DownExpand Up@@ -111,6 +112,9 @@ function writeE2EMetadata() {
const e2e = (fn: string) =>
 getWorkflowMetadata(deploymentUrl, 'workflows/99_e2e.ts', fn);

const workflowWebhookUrl = (token: string) =>
 createWorkflowUrl(deploymentUrl, { type: 'webhook', token });

type WorkflowEvent = Awaited<
 ReturnType<World['events']['list']>
>['data'][number];
Expand DownExpand Up@@ -532,17 +536,11 @@ describe('e2e', () => {
 expect(hook.runId).toBe(run.runId);

 // Attempt to resume via the public webhook endpoint — should get 404
 const res = await fetch(
 new URL(
 `/.well-known/workflow/v1/webhook/${encodeURIComponent(token)}`,
 deploymentUrl
 ),
 {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: JSON.stringify({ message: 'should-be-rejected' }),
 }
 );
 const res = await fetch(workflowWebhookUrl(token), {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: JSON.stringify({ message: 'should-be-rejected' }),
 });
 expect(res.status).toBe(404);

 // Now resume via server-side resumeHook() — should work
Expand DownExpand Up@@ -587,79 +585,46 @@ describe('e2e', () => {
 const [token, token2, token3] = hooks.map((h) => h.token);

 // Webhook with default response
 const res = await fetch(
 new URL(
 `/.well-known/workflow/v1/webhook/${encodeURIComponent(token)}`,
 deploymentUrl
 ),
 {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: JSON.stringify({ message: 'one' }),
 }
 );
 const res = await fetch(workflowWebhookUrl(token), {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: JSON.stringify({ message: 'one' }),
 });
 expect(res.status).toBe(202);
 const body = await res.text();
 expect(body).toBe('');

 // Webhook with static response
 const res2 = await fetch(
 new URL(
 `/.well-known/workflow/v1/webhook/${encodeURIComponent(token2)}`,
 deploymentUrl
 ),
 {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: JSON.stringify({ message: 'two' }),
 }
 );
 const res2 = await fetch(workflowWebhookUrl(token2), {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: JSON.stringify({ message: 'two' }),
 });
 expect(res2.status).toBe(402);
 const body2 = await res2.text();
 expect(body2).toBe('Hello from static response!');

 // Webhook with manual response
 const res3 = await fetch(
 new URL(
 `/.well-known/workflow/v1/webhook/${encodeURIComponent(token3)}`,
 deploymentUrl
 ),
 {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: JSON.stringify({ message: 'three' }),
 }
 );
 const res3 = await fetch(workflowWebhookUrl(token3), {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: JSON.stringify({ message: 'three' }),
 });
 expect(res3.status).toBe(200);
 const body3 = await res3.text();
 expect(body3).toBe('Hello from webhook!');

 const returnValue = await run.returnValue;
 expect(returnValue).toHaveLength(3);
 expect(returnValue[0].url).toBe(
 new URL(
 `/.well-known/workflow/v1/webhook/${encodeURIComponent(token)}`,
 deploymentUrl
 ).href
 );
 expect(returnValue[0].url).toBe(workflowWebhookUrl(token));
 expect(returnValue[0].method).toBe('POST');
 expect(returnValue[0].body).toBe('{"message":"one"}');

 expect(returnValue[1].url).toBe(
 new URL(
 `/.well-known/workflow/v1/webhook/${encodeURIComponent(token2)}`,
 deploymentUrl
 ).href
 );
 expect(returnValue[1].url).toBe(workflowWebhookUrl(token2));
 expect(returnValue[1].method).toBe('POST');
 expect(returnValue[1].body).toBe('{"message":"two"}');

 expect(returnValue[2].url).toBe(
 new URL(
 `/.well-known/workflow/v1/webhook/${encodeURIComponent(token3)}`,
 deploymentUrl
 ).href
 );
 expect(returnValue[2].url).toBe(workflowWebhookUrl(token3));
 expect(returnValue[2].method).toBe('POST');
 expect(returnValue[2].body).toBe('{"message":"three"}');
 });
Expand DownExpand Up@@ -730,17 +695,11 @@ describe('e2e', () => {
 continue;
 }

 const res = await fetch(
 new URL(
 `/.well-known/workflow/v1/webhook/${encodeURIComponent(unservedHook.token)}`,
 deploymentUrl
 ),
 {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: `body-${unservedHook.token}`,
 }
 );
 const res = await fetch(workflowWebhookUrl(unservedHook.token), {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: `body-${unservedHook.token}`,
 });
 expect(res.status).toBe(202);
 servedTokens.add(unservedHook.token);
 }
Expand DownExpand Up@@ -786,11 +745,7 @@ describe('e2e', () => {
 );

 test('webhook route with invalid token', { timeout: 60_000 }, async () => {
 const invalidWebhookUrl = new URL(
 `/.well-known/workflow/v1/webhook/${encodeURIComponent('invalid')}`,
 deploymentUrl
 );
 const res = await fetch(invalidWebhookUrl, {
 const res = await fetch(workflowWebhookUrl('invalid'), {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: JSON.stringify({}),
Expand DownExpand Up@@ -2555,14 +2510,13 @@ describe('e2e', () => {
 // bypasses protection by sending messages through the Queue infrastructure.

 // Test the flow endpoint health check (V2: combined handler for both workflow + step)
 const flowHealthUrl = new URL(
 '/.well-known/workflow/v1/flow?__health',
 deploymentUrl
 const flowRes = await fetch(
 createWorkflowUrl(deploymentUrl, { type: 'health' }),
 {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 }
 );
 const flowRes = await fetch(flowHealthUrl, {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 });
 expect(flowRes.status).toBe(200);
 expect(flowRes.headers.get('Content-Type')).toBe('application/json');
 const flowBody = await flowRes.json();
Expand Down

3 changes: 2 additions & 1 deletion
packages/core/e2e/utils.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -3,6 +3,7 @@ import fs from 'node:fs';
import path, { dirname } from 'node:path';
import { setTimeout as sleep } from 'node:timers/promises';
import { fileURLToPath } from 'node:url';
import { createWorkflowUrl } from '@workflow/utils';
import { createVercelWorld } from '@workflow/world-vercel';
import { onTestFailed } from 'vitest';
import { getTrustedSourcesHeaders } from '../../../scripts/trusted-sources-headers.mjs';
Expand DownExpand Up@@ -373,7 +374,7 @@ export async function fetchManifest(
 const forceRefresh = options?.forceRefresh ?? false;
 if (cachedManifest && !forceRefresh) return cachedManifest;

 const url = new URL('/.well-known/workflow/v1/manifest.json', deploymentUrl);
 const url = createWorkflowUrl(deploymentUrl, { type: 'manifest' });
 const res = await fetch(url, {
 headers: await getTrustedSourcesHeaders(),
 });
Expand Down

4 changes: 2 additions & 2 deletions
packages/core/src/create-hook.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -167,8 +167,8 @@ export interface HookOptions {
 * Whether this hook can be resumed via the public webhook endpoint.
 *
 * When `true`, the hook can be triggered by sending an HTTP request to the
 * public `/.well-known/workflow/v1/webhook/{token}` URL. This is automatically
 * set when using `createWebhook()`.
 * public workflowwebhook URL. This is automatically set when using
 * `createWebhook()`.
 *
 * When `false` (the default), the hook can only be resumed server-side
 * via `resumeHook()`.
Expand Down

9 changes: 8 additions & 1 deletion
packages/core/src/runtime.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -9,6 +9,7 @@ import {
 RunExpiredError,
 WorkflowRuntimeError,
} from '@workflow/errors';
import { setWorkflowBasePath } from '@workflow/utils';
import {
 parseWorkflowName,
 workflowDisplayName,
Expand DownExpand Up@@ -293,8 +294,14 @@ function hasOpenHookOrWait(events: Event[]): boolean {
 */
export function workflowEntrypoint(
 workflowCode: string,
 options?: { namespace?: string; routeModuleBodyStartedAt?: number }
 options?: {
 namespace?: string;
 routeModuleBodyStartedAt?: number;
 basePath?: string;
 }
): (req: Request) => Promise<Response> {
 setWorkflowBasePath(options?.basePath);

 const NO_INLINE_REPLAY_AFTER_MS =
 Number(process.env.WORKFLOW_V2_TIMEOUT_MS) || 120_000;

Expand Down
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Force GitHub README to respect dark mode
(function() {
var style = document.createElement('style');
style.textContent = '
.markdown-body {
color-scheme: dark light;
}
.markdown-body pre { background: #161b22 !important; }
.markdown-body code { background: rgba(110, 118, 129, 0.4) !important; }
.markdown-body table th, .markdown-body table td { border-color: #30363d !important; }
.markdown-body img { background: #0d1117; }
.markdown-body blockquote { border-left-color: #8b949e; }
.markdown-body hr { border-color: #30363d; }
';
document.head.appendChild(style);
})();
}
} catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '
fix(next): respect basePath for workflow routes by NathanColosimo · Pull Request #2732 · vercel/workflow · GitHub
Skip to content
fix(next): respect basePath for workflow routes#2732

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

NathanColosimo
merged 9 commits into

from

Jul 6, 2026
 Merged


fix(next): respect basePath for workflow routes
#2732
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


9 commits


Select commit
Hold shift + click to select a range
7b44046

fix(next): respect basePath for workflow routes


NathanColosimo Jul 2, 2026
d06c57f

docs(core): note workflow URL resolution gap


NathanColosimo Jul 2, 2026
610c9c0

fix(next): expose workflow health route methods


NathanColosimo Jul 2, 2026
18a9a2d

test(utils): remove workflow route helper tests


NathanColosimo Jul 2, 2026
0017fca

test(builders): remove route handler string test


NathanColosimo Jul 2, 2026
cbbd394

fix(next): defer basePath validation to Next.js


NathanColosimo Jul 2, 2026
e157fba

refactor(utils): remove workflow url helper wrappers


NathanColosimo Jul 2, 2026
4fb7f19

Test Next basePath builder wiring


NathanColosimo Jul 6, 2026
ce1ddb2

Merge remote-tracking branch 'origin/main' into nathanc/fix-next-base…


NathanColosimo Jul 6, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


10 changes: 10 additions & 0 deletions
.changeset/next-base-path.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
---
"@workflow/builders": patch
"@workflow/core": patch
"@workflow/next": patch
"@workflow/utils": patch
"@workflow/world-local": patch
"@workflow/world-postgres": patch
---

Respect framework base paths when routing workflow traffic and expose health checks on generated Next.js workflow routes.

14 changes: 10 additions & 4 deletions
packages/builders/src/base-builder.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -23,7 +23,10 @@ import {
 applySwcTransform,
 type WorkflowManifest,
} from './apply-swc-transform.js';
import { createWorkflowEntrypointOptionsCode } from './constants.js';
import {
 createWorkflowEntrypointOptionsCode,
 createWorkflowRouteHandlersCode,
} from './constants.js';
import { getEsbuildTsconfigOptions } from './esbuild-tsconfig.js';
import {
 type DiscoveredEntries,
Expand DownExpand Up@@ -1564,6 +1567,7 @@ export const __steps_registered = true;

 const workflowEntrypointOptionsCode = createWorkflowEntrypointOptionsCode(
 {
 basePath: this.config.basePath,
 routeModuleBodyStartedAt: 'workflowRouteModuleBodyStartedAt',
 }
 );
Expand All@@ -1578,7 +1582,7 @@ import { workflowEntrypoint } from 'workflow/runtime';
const workflowRouteModuleBodyStartedAt = Date.now();
const workflowCode = \`${workflowBundleCode.replace(/[\\`$]/g, '\\$&')}\`;

export const POST = workflowEntrypoint(workflowCode${workflowEntrypointOptionsCode});`;
${createWorkflowRouteHandlersCode(`workflowEntrypoint(workflowCode${workflowEntrypointOptionsCode})`)}`;

 // we skip the final bundling step for Next.js so it can bundle itself
 if (!bundleFinalOutput) {
Expand DownExpand Up@@ -1771,6 +1775,7 @@ export const POST = workflowEntrypoint(workflowCode${workflowEntrypointOptionsCo
 const stepsRelativePath = `./${basename(stepsOutfile).replace(/\\/g, '/')}`;
 const escapedVMCode = workflowVMCode.replace(/[\\`$]/g, '\\$&');
 const workflowEntrypointOptionsCode = createWorkflowEntrypointOptionsCode({
 basePath: this.config.basePath,
 routeModuleBodyStartedAt: 'workflowRouteModuleBodyStartedAt',
 });

Expand All@@ -1786,7 +1791,7 @@ void __steps_registered;

const workflowCode = \`${escapedVMCode}\`;

export const POST = workflowEntrypoint(workflowCode${workflowEntrypointOptionsCode});`;
${createWorkflowRouteHandlersCode(`workflowEntrypoint(workflowCode${workflowEntrypointOptionsCode})`)}`;

 if (!bundleFinalOutput) {
 await this.writeGeneratedFile(flowOutfile, combinedFunctionCode);
Expand DownExpand Up@@ -1849,6 +1854,7 @@ export const POST = workflowEntrypoint(workflowCode${workflowEntrypointOptionsCo
 const escaped = interimBundleText.replace(/[\\`$]/g, '\\$&');
 const workflowEntrypointOptionsCode = createWorkflowEntrypointOptionsCode(
 {
 basePath: this.config.basePath,
 routeModuleBodyStartedAt: 'workflowRouteModuleBodyStartedAt',
 }
 );
Expand All@@ -1864,7 +1870,7 @@ void __steps_registered;

const workflowCode = \`${escaped}\`;

export const POST = workflowEntrypoint(workflowCode${workflowEntrypointOptionsCode});`;
${createWorkflowRouteHandlersCode(`workflowEntrypoint(workflowCode${workflowEntrypointOptionsCode})`)}`;

 const outputDir = dirname(flowOutfile);
 await mkdir(outputDir, { recursive: true });
Expand Down

3 changes: 2 additions & 1 deletion
packages/builders/src/constants.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -53,10 +53,11 @@ describe('createWorkflowEntrypointOptionsCode', () => {
 expect(
 createWorkflowEntrypointOptionsCode({
 namespace: 'custom',
 basePath: '/v2',
 routeModuleBodyStartedAt: 'workflowRouteModuleBodyStartedAt',
 })
 ).toBe(
 ', { namespace: "custom", routeModuleBodyStartedAt: workflowRouteModuleBodyStartedAt }'
 ', { namespace: "custom", basePath: "/v2", routeModuleBodyStartedAt: workflowRouteModuleBodyStartedAt }'
 );
 });
});

14 changes: 14 additions & 0 deletions
packages/builders/src/constants.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -54,6 +54,7 @@ export function createWorkflowQueueTrigger(options?: { namespace?: string }) {
 */
export function createWorkflowEntrypointOptionsCode(options?: {
 namespace?: string;
 basePath?: string;
 /** Raw code identifier/expression emitted into generated route files, not data. */
 routeModuleBodyStartedAt?: string;
}) {
Expand All@@ -66,6 +67,10 @@ export function createWorkflowEntrypointOptionsCode(options?: {
 fields.push(`namespace: ${JSON.stringify(namespace)}`);
 }

 if (options?.basePath !== undefined) {
 fields.push(`basePath: ${JSON.stringify(options.basePath)}`);
 }

 if (options?.routeModuleBodyStartedAt) {
 fields.push(
 `routeModuleBodyStartedAt: ${options.routeModuleBodyStartedAt}`
Expand All@@ -79,6 +84,15 @@ export function createWorkflowEntrypointOptionsCode(options?: {
 return `, { ${fields.join(', ')} }`;
}

export function createWorkflowRouteHandlersCode(
 workflowEntrypointCall: string
) {
 return `export const POST = ${workflowEntrypointCall};
export const GET = POST;
export const HEAD = POST;
export const OPTIONS = POST;`;
}

/**
 * Default queue trigger (no namespace). Backward compatible.
 */
Expand Down

3 changes: 3 additions & 0 deletions
packages/builders/src/types.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -60,6 +60,9 @@ interface BaseWorkflowConfig {
 // artifact locations.
 distDir?: string;

 // Optional route prefix for apps deployed below the origin root.
 basePath?: string;

 // Suppress informational logs emitted by createWorkflowsBundle()
 // (e.g. intermediate/final workflow bundle timing logs).
 suppressCreateWorkflowsBundleLogs?: boolean;
Expand Down

124 changes: 39 additions & 85 deletions
packages/core/e2e/e2e.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -10,6 +10,7 @@ import {
 WorkflowRunFailedError,
 WorkflowWorldError,
} from '@workflow/errors';
import { createWorkflowUrl } from '@workflow/utils';
import { SPEC_VERSION_CURRENT, type World } from '@workflow/world';
import {
 afterAll,
Expand DownExpand Up@@ -111,6 +112,9 @@ function writeE2EMetadata() {
const e2e = (fn: string) =>
 getWorkflowMetadata(deploymentUrl, 'workflows/99_e2e.ts', fn);

const workflowWebhookUrl = (token: string) =>
 createWorkflowUrl(deploymentUrl, { type: 'webhook', token });

type WorkflowEvent = Awaited<
 ReturnType<World['events']['list']>
>['data'][number];
Expand DownExpand Up@@ -532,17 +536,11 @@ describe('e2e', () => {
 expect(hook.runId).toBe(run.runId);

 // Attempt to resume via the public webhook endpoint — should get 404
 const res = await fetch(
 new URL(
 `/.well-known/workflow/v1/webhook/${encodeURIComponent(token)}`,
 deploymentUrl
 ),
 {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: JSON.stringify({ message: 'should-be-rejected' }),
 }
 );
 const res = await fetch(workflowWebhookUrl(token), {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: JSON.stringify({ message: 'should-be-rejected' }),
 });
 expect(res.status).toBe(404);

 // Now resume via server-side resumeHook() — should work
Expand DownExpand Up@@ -587,79 +585,46 @@ describe('e2e', () => {
 const [token, token2, token3] = hooks.map((h) => h.token);

 // Webhook with default response
 const res = await fetch(
 new URL(
 `/.well-known/workflow/v1/webhook/${encodeURIComponent(token)}`,
 deploymentUrl
 ),
 {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: JSON.stringify({ message: 'one' }),
 }
 );
 const res = await fetch(workflowWebhookUrl(token), {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: JSON.stringify({ message: 'one' }),
 });
 expect(res.status).toBe(202);
 const body = await res.text();
 expect(body).toBe('');

 // Webhook with static response
 const res2 = await fetch(
 new URL(
 `/.well-known/workflow/v1/webhook/${encodeURIComponent(token2)}`,
 deploymentUrl
 ),
 {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: JSON.stringify({ message: 'two' }),
 }
 );
 const res2 = await fetch(workflowWebhookUrl(token2), {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: JSON.stringify({ message: 'two' }),
 });
 expect(res2.status).toBe(402);
 const body2 = await res2.text();
 expect(body2).toBe('Hello from static response!');

 // Webhook with manual response
 const res3 = await fetch(
 new URL(
 `/.well-known/workflow/v1/webhook/${encodeURIComponent(token3)}`,
 deploymentUrl
 ),
 {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: JSON.stringify({ message: 'three' }),
 }
 );
 const res3 = await fetch(workflowWebhookUrl(token3), {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: JSON.stringify({ message: 'three' }),
 });
 expect(res3.status).toBe(200);
 const body3 = await res3.text();
 expect(body3).toBe('Hello from webhook!');

 const returnValue = await run.returnValue;
 expect(returnValue).toHaveLength(3);
 expect(returnValue[0].url).toBe(
 new URL(
 `/.well-known/workflow/v1/webhook/${encodeURIComponent(token)}`,
 deploymentUrl
 ).href
 );
 expect(returnValue[0].url).toBe(workflowWebhookUrl(token));
 expect(returnValue[0].method).toBe('POST');
 expect(returnValue[0].body).toBe('{"message":"one"}');

 expect(returnValue[1].url).toBe(
 new URL(
 `/.well-known/workflow/v1/webhook/${encodeURIComponent(token2)}`,
 deploymentUrl
 ).href
 );
 expect(returnValue[1].url).toBe(workflowWebhookUrl(token2));
 expect(returnValue[1].method).toBe('POST');
 expect(returnValue[1].body).toBe('{"message":"two"}');

 expect(returnValue[2].url).toBe(
 new URL(
 `/.well-known/workflow/v1/webhook/${encodeURIComponent(token3)}`,
 deploymentUrl
 ).href
 );
 expect(returnValue[2].url).toBe(workflowWebhookUrl(token3));
 expect(returnValue[2].method).toBe('POST');
 expect(returnValue[2].body).toBe('{"message":"three"}');
 });
Expand DownExpand Up@@ -730,17 +695,11 @@ describe('e2e', () => {
 continue;
 }

 const res = await fetch(
 new URL(
 `/.well-known/workflow/v1/webhook/${encodeURIComponent(unservedHook.token)}`,
 deploymentUrl
 ),
 {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: `body-${unservedHook.token}`,
 }
 );
 const res = await fetch(workflowWebhookUrl(unservedHook.token), {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: `body-${unservedHook.token}`,
 });
 expect(res.status).toBe(202);
 servedTokens.add(unservedHook.token);
 }
Expand DownExpand Up@@ -786,11 +745,7 @@ describe('e2e', () => {
 );

 test('webhook route with invalid token', { timeout: 60_000 }, async () => {
 const invalidWebhookUrl = new URL(
 `/.well-known/workflow/v1/webhook/${encodeURIComponent('invalid')}`,
 deploymentUrl
 );
 const res = await fetch(invalidWebhookUrl, {
 const res = await fetch(workflowWebhookUrl('invalid'), {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: JSON.stringify({}),
Expand DownExpand Up@@ -2555,14 +2510,13 @@ describe('e2e', () => {
 // bypasses protection by sending messages through the Queue infrastructure.

 // Test the flow endpoint health check (V2: combined handler for both workflow + step)
 const flowHealthUrl = new URL(
 '/.well-known/workflow/v1/flow?__health',
 deploymentUrl
 const flowRes = await fetch(
 createWorkflowUrl(deploymentUrl, { type: 'health' }),
 {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 }
 );
 const flowRes = await fetch(flowHealthUrl, {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 });
 expect(flowRes.status).toBe(200);
 expect(flowRes.headers.get('Content-Type')).toBe('application/json');
 const flowBody = await flowRes.json();
Expand Down

3 changes: 2 additions & 1 deletion
packages/core/e2e/utils.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -3,6 +3,7 @@ import fs from 'node:fs';
import path, { dirname } from 'node:path';
import { setTimeout as sleep } from 'node:timers/promises';
import { fileURLToPath } from 'node:url';
import { createWorkflowUrl } from '@workflow/utils';
import { createVercelWorld } from '@workflow/world-vercel';
import { onTestFailed } from 'vitest';
import { getTrustedSourcesHeaders } from '../../../scripts/trusted-sources-headers.mjs';
Expand DownExpand Up@@ -373,7 +374,7 @@ export async function fetchManifest(
 const forceRefresh = options?.forceRefresh ?? false;
 if (cachedManifest && !forceRefresh) return cachedManifest;

 const url = new URL('/.well-known/workflow/v1/manifest.json', deploymentUrl);
 const url = createWorkflowUrl(deploymentUrl, { type: 'manifest' });
 const res = await fetch(url, {
 headers: await getTrustedSourcesHeaders(),
 });
Expand Down

4 changes: 2 additions & 2 deletions
packages/core/src/create-hook.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -167,8 +167,8 @@ export interface HookOptions {
 * Whether this hook can be resumed via the public webhook endpoint.
 *
 * When `true`, the hook can be triggered by sending an HTTP request to the
 * public `/.well-known/workflow/v1/webhook/{token}` URL. This is automatically
 * set when using `createWebhook()`.
 * public workflowwebhook URL. This is automatically set when using
 * `createWebhook()`.
 *
 * When `false` (the default), the hook can only be resumed server-side
 * via `resumeHook()`.
Expand Down

9 changes: 8 additions & 1 deletion
packages/core/src/runtime.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -9,6 +9,7 @@ import {
 RunExpiredError,
 WorkflowRuntimeError,
} from '@workflow/errors';
import { setWorkflowBasePath } from '@workflow/utils';
import {
 parseWorkflowName,
 workflowDisplayName,
Expand DownExpand Up@@ -293,8 +294,14 @@ function hasOpenHookOrWait(events: Event[]): boolean {
 */
export function workflowEntrypoint(
 workflowCode: string,
 options?: { namespace?: string; routeModuleBodyStartedAt?: number }
 options?: {
 namespace?: string;
 routeModuleBodyStartedAt?: number;
 basePath?: string;
 }
): (req: Request) => Promise<Response> {
 setWorkflowBasePath(options?.basePath);

 const NO_INLINE_REPLAY_AFTER_MS =
 Number(process.env.WORKFLOW_V2_TIMEOUT_MS) || 120_000;

Expand Down
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Highlight search terms from Google/DuckDuckGo/Bing referrer
(function() {
var ref = document.referrer;
var terms = [];
if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) {
var url = new URL(ref);
var q = url.searchParams.get('q') || url.searchParams.get('p');
if (q) {
terms = q.split(/\s+/).filter(function(t) { return t.length > 2; });
}
}
if (terms.length === 0) return;
var style = document.createElement('style');
style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }';
document.head.appendChild(style);
function highlight(node) {
if (node.nodeType === 3) { // text node
var text = node.textContent;
var found = false;
terms.forEach(function(term) {
var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\]\\]/g, '\\') + ')', 'gi');
if (regex.test(text)) {
found = true;
var frag = document.createDocumentFragment();
var parts = text.split(regex);
parts.forEach(function(part, i) {
if (i % 2 === 0) {
frag.appendChild(document.createTextNode(part));
} else {
var span = document.createElement('span');
span.className = 'userscript-highlight';
span.textContent = part;
frag.appendChild(span);
}
});
node.parentNode.replaceChild(frag, node);
}
});
} else if (node.nodeType === 1 && node.childNodes) { // element
var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT'];
if (!skipTags.includes(node.tagName)) {
Array.from(node.childNodes).forEach(highlight);
}
}
}
highlight(document.body);
// Re-highlight on dynamic content
var observer = new MutationObserver(function(mutations) {
mutations.forEach(function(m) {
m.addedNodes.forEach(function(node) {
if (node.nodeType === 1 || node.nodeType === 3) highlight(node);
});
});
});
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '
fix(next): respect basePath for workflow routes by NathanColosimo · Pull Request #2732 · vercel/workflow · GitHub
Skip to content
fix(next): respect basePath for workflow routes#2732

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

NathanColosimo
merged 9 commits into

from

Jul 6, 2026
 Merged


fix(next): respect basePath for workflow routes
#2732
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


9 commits


Select commit
Hold shift + click to select a range
7b44046

fix(next): respect basePath for workflow routes


NathanColosimo Jul 2, 2026
d06c57f

docs(core): note workflow URL resolution gap


NathanColosimo Jul 2, 2026
610c9c0

fix(next): expose workflow health route methods


NathanColosimo Jul 2, 2026
18a9a2d

test(utils): remove workflow route helper tests


NathanColosimo Jul 2, 2026
0017fca

test(builders): remove route handler string test


NathanColosimo Jul 2, 2026
cbbd394

fix(next): defer basePath validation to Next.js


NathanColosimo Jul 2, 2026
e157fba

refactor(utils): remove workflow url helper wrappers


NathanColosimo Jul 2, 2026
4fb7f19

Test Next basePath builder wiring


NathanColosimo Jul 6, 2026
ce1ddb2

Merge remote-tracking branch 'origin/main' into nathanc/fix-next-base…


NathanColosimo Jul 6, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


10 changes: 10 additions & 0 deletions
.changeset/next-base-path.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
---
"@workflow/builders": patch
"@workflow/core": patch
"@workflow/next": patch
"@workflow/utils": patch
"@workflow/world-local": patch
"@workflow/world-postgres": patch
---

Respect framework base paths when routing workflow traffic and expose health checks on generated Next.js workflow routes.

14 changes: 10 additions & 4 deletions
packages/builders/src/base-builder.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -23,7 +23,10 @@ import {
 applySwcTransform,
 type WorkflowManifest,
} from './apply-swc-transform.js';
import { createWorkflowEntrypointOptionsCode } from './constants.js';
import {
 createWorkflowEntrypointOptionsCode,
 createWorkflowRouteHandlersCode,
} from './constants.js';
import { getEsbuildTsconfigOptions } from './esbuild-tsconfig.js';
import {
 type DiscoveredEntries,
Expand DownExpand Up@@ -1564,6 +1567,7 @@ export const __steps_registered = true;

 const workflowEntrypointOptionsCode = createWorkflowEntrypointOptionsCode(
 {
 basePath: this.config.basePath,
 routeModuleBodyStartedAt: 'workflowRouteModuleBodyStartedAt',
 }
 );
Expand All@@ -1578,7 +1582,7 @@ import { workflowEntrypoint } from 'workflow/runtime';
const workflowRouteModuleBodyStartedAt = Date.now();
const workflowCode = \`${workflowBundleCode.replace(/[\\`$]/g, '\\$&')}\`;

export const POST = workflowEntrypoint(workflowCode${workflowEntrypointOptionsCode});`;
${createWorkflowRouteHandlersCode(`workflowEntrypoint(workflowCode${workflowEntrypointOptionsCode})`)}`;

 // we skip the final bundling step for Next.js so it can bundle itself
 if (!bundleFinalOutput) {
Expand DownExpand Up@@ -1771,6 +1775,7 @@ export const POST = workflowEntrypoint(workflowCode${workflowEntrypointOptionsCo
 const stepsRelativePath = `./${basename(stepsOutfile).replace(/\\/g, '/')}`;
 const escapedVMCode = workflowVMCode.replace(/[\\`$]/g, '\\$&');
 const workflowEntrypointOptionsCode = createWorkflowEntrypointOptionsCode({
 basePath: this.config.basePath,
 routeModuleBodyStartedAt: 'workflowRouteModuleBodyStartedAt',
 });

Expand All@@ -1786,7 +1791,7 @@ void __steps_registered;

const workflowCode = \`${escapedVMCode}\`;

export const POST = workflowEntrypoint(workflowCode${workflowEntrypointOptionsCode});`;
${createWorkflowRouteHandlersCode(`workflowEntrypoint(workflowCode${workflowEntrypointOptionsCode})`)}`;

 if (!bundleFinalOutput) {
 await this.writeGeneratedFile(flowOutfile, combinedFunctionCode);
Expand DownExpand Up@@ -1849,6 +1854,7 @@ export const POST = workflowEntrypoint(workflowCode${workflowEntrypointOptionsCo
 const escaped = interimBundleText.replace(/[\\`$]/g, '\\$&');
 const workflowEntrypointOptionsCode = createWorkflowEntrypointOptionsCode(
 {
 basePath: this.config.basePath,
 routeModuleBodyStartedAt: 'workflowRouteModuleBodyStartedAt',
 }
 );
Expand All@@ -1864,7 +1870,7 @@ void __steps_registered;

const workflowCode = \`${escaped}\`;

export const POST = workflowEntrypoint(workflowCode${workflowEntrypointOptionsCode});`;
${createWorkflowRouteHandlersCode(`workflowEntrypoint(workflowCode${workflowEntrypointOptionsCode})`)}`;

 const outputDir = dirname(flowOutfile);
 await mkdir(outputDir, { recursive: true });
Expand Down

3 changes: 2 additions & 1 deletion
packages/builders/src/constants.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -53,10 +53,11 @@ describe('createWorkflowEntrypointOptionsCode', () => {
 expect(
 createWorkflowEntrypointOptionsCode({
 namespace: 'custom',
 basePath: '/v2',
 routeModuleBodyStartedAt: 'workflowRouteModuleBodyStartedAt',
 })
 ).toBe(
 ', { namespace: "custom", routeModuleBodyStartedAt: workflowRouteModuleBodyStartedAt }'
 ', { namespace: "custom", basePath: "/v2", routeModuleBodyStartedAt: workflowRouteModuleBodyStartedAt }'
 );
 });
});

14 changes: 14 additions & 0 deletions
packages/builders/src/constants.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -54,6 +54,7 @@ export function createWorkflowQueueTrigger(options?: { namespace?: string }) {
 */
export function createWorkflowEntrypointOptionsCode(options?: {
 namespace?: string;
 basePath?: string;
 /** Raw code identifier/expression emitted into generated route files, not data. */
 routeModuleBodyStartedAt?: string;
}) {
Expand All@@ -66,6 +67,10 @@ export function createWorkflowEntrypointOptionsCode(options?: {
 fields.push(`namespace: ${JSON.stringify(namespace)}`);
 }

 if (options?.basePath !== undefined) {
 fields.push(`basePath: ${JSON.stringify(options.basePath)}`);
 }

 if (options?.routeModuleBodyStartedAt) {
 fields.push(
 `routeModuleBodyStartedAt: ${options.routeModuleBodyStartedAt}`
Expand All@@ -79,6 +84,15 @@ export function createWorkflowEntrypointOptionsCode(options?: {
 return `, { ${fields.join(', ')} }`;
}

export function createWorkflowRouteHandlersCode(
 workflowEntrypointCall: string
) {
 return `export const POST = ${workflowEntrypointCall};
export const GET = POST;
export const HEAD = POST;
export const OPTIONS = POST;`;
}

/**
 * Default queue trigger (no namespace). Backward compatible.
 */
Expand Down

3 changes: 3 additions & 0 deletions
packages/builders/src/types.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -60,6 +60,9 @@ interface BaseWorkflowConfig {
 // artifact locations.
 distDir?: string;

 // Optional route prefix for apps deployed below the origin root.
 basePath?: string;

 // Suppress informational logs emitted by createWorkflowsBundle()
 // (e.g. intermediate/final workflow bundle timing logs).
 suppressCreateWorkflowsBundleLogs?: boolean;
Expand Down

124 changes: 39 additions & 85 deletions
packages/core/e2e/e2e.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -10,6 +10,7 @@ import {
 WorkflowRunFailedError,
 WorkflowWorldError,
} from '@workflow/errors';
import { createWorkflowUrl } from '@workflow/utils';
import { SPEC_VERSION_CURRENT, type World } from '@workflow/world';
import {
 afterAll,
Expand DownExpand Up@@ -111,6 +112,9 @@ function writeE2EMetadata() {
const e2e = (fn: string) =>
 getWorkflowMetadata(deploymentUrl, 'workflows/99_e2e.ts', fn);

const workflowWebhookUrl = (token: string) =>
 createWorkflowUrl(deploymentUrl, { type: 'webhook', token });

type WorkflowEvent = Awaited<
 ReturnType<World['events']['list']>
>['data'][number];
Expand DownExpand Up@@ -532,17 +536,11 @@ describe('e2e', () => {
 expect(hook.runId).toBe(run.runId);

 // Attempt to resume via the public webhook endpoint — should get 404
 const res = await fetch(
 new URL(
 `/.well-known/workflow/v1/webhook/${encodeURIComponent(token)}`,
 deploymentUrl
 ),
 {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: JSON.stringify({ message: 'should-be-rejected' }),
 }
 );
 const res = await fetch(workflowWebhookUrl(token), {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: JSON.stringify({ message: 'should-be-rejected' }),
 });
 expect(res.status).toBe(404);

 // Now resume via server-side resumeHook() — should work
Expand DownExpand Up@@ -587,79 +585,46 @@ describe('e2e', () => {
 const [token, token2, token3] = hooks.map((h) => h.token);

 // Webhook with default response
 const res = await fetch(
 new URL(
 `/.well-known/workflow/v1/webhook/${encodeURIComponent(token)}`,
 deploymentUrl
 ),
 {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: JSON.stringify({ message: 'one' }),
 }
 );
 const res = await fetch(workflowWebhookUrl(token), {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: JSON.stringify({ message: 'one' }),
 });
 expect(res.status).toBe(202);
 const body = await res.text();
 expect(body).toBe('');

 // Webhook with static response
 const res2 = await fetch(
 new URL(
 `/.well-known/workflow/v1/webhook/${encodeURIComponent(token2)}`,
 deploymentUrl
 ),
 {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: JSON.stringify({ message: 'two' }),
 }
 );
 const res2 = await fetch(workflowWebhookUrl(token2), {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: JSON.stringify({ message: 'two' }),
 });
 expect(res2.status).toBe(402);
 const body2 = await res2.text();
 expect(body2).toBe('Hello from static response!');

 // Webhook with manual response
 const res3 = await fetch(
 new URL(
 `/.well-known/workflow/v1/webhook/${encodeURIComponent(token3)}`,
 deploymentUrl
 ),
 {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: JSON.stringify({ message: 'three' }),
 }
 );
 const res3 = await fetch(workflowWebhookUrl(token3), {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: JSON.stringify({ message: 'three' }),
 });
 expect(res3.status).toBe(200);
 const body3 = await res3.text();
 expect(body3).toBe('Hello from webhook!');

 const returnValue = await run.returnValue;
 expect(returnValue).toHaveLength(3);
 expect(returnValue[0].url).toBe(
 new URL(
 `/.well-known/workflow/v1/webhook/${encodeURIComponent(token)}`,
 deploymentUrl
 ).href
 );
 expect(returnValue[0].url).toBe(workflowWebhookUrl(token));
 expect(returnValue[0].method).toBe('POST');
 expect(returnValue[0].body).toBe('{"message":"one"}');

 expect(returnValue[1].url).toBe(
 new URL(
 `/.well-known/workflow/v1/webhook/${encodeURIComponent(token2)}`,
 deploymentUrl
 ).href
 );
 expect(returnValue[1].url).toBe(workflowWebhookUrl(token2));
 expect(returnValue[1].method).toBe('POST');
 expect(returnValue[1].body).toBe('{"message":"two"}');

 expect(returnValue[2].url).toBe(
 new URL(
 `/.well-known/workflow/v1/webhook/${encodeURIComponent(token3)}`,
 deploymentUrl
 ).href
 );
 expect(returnValue[2].url).toBe(workflowWebhookUrl(token3));
 expect(returnValue[2].method).toBe('POST');
 expect(returnValue[2].body).toBe('{"message":"three"}');
 });
Expand DownExpand Up@@ -730,17 +695,11 @@ describe('e2e', () => {
 continue;
 }

 const res = await fetch(
 new URL(
 `/.well-known/workflow/v1/webhook/${encodeURIComponent(unservedHook.token)}`,
 deploymentUrl
 ),
 {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: `body-${unservedHook.token}`,
 }
 );
 const res = await fetch(workflowWebhookUrl(unservedHook.token), {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: `body-${unservedHook.token}`,
 });
 expect(res.status).toBe(202);
 servedTokens.add(unservedHook.token);
 }
Expand DownExpand Up@@ -786,11 +745,7 @@ describe('e2e', () => {
 );

 test('webhook route with invalid token', { timeout: 60_000 }, async () => {
 const invalidWebhookUrl = new URL(
 `/.well-known/workflow/v1/webhook/${encodeURIComponent('invalid')}`,
 deploymentUrl
 );
 const res = await fetch(invalidWebhookUrl, {
 const res = await fetch(workflowWebhookUrl('invalid'), {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: JSON.stringify({}),
Expand DownExpand Up@@ -2555,14 +2510,13 @@ describe('e2e', () => {
 // bypasses protection by sending messages through the Queue infrastructure.

 // Test the flow endpoint health check (V2: combined handler for both workflow + step)
 const flowHealthUrl = new URL(
 '/.well-known/workflow/v1/flow?__health',
 deploymentUrl
 const flowRes = await fetch(
 createWorkflowUrl(deploymentUrl, { type: 'health' }),
 {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 }
 );
 const flowRes = await fetch(flowHealthUrl, {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 });
 expect(flowRes.status).toBe(200);
 expect(flowRes.headers.get('Content-Type')).toBe('application/json');
 const flowBody = await flowRes.json();
Expand Down

3 changes: 2 additions & 1 deletion
packages/core/e2e/utils.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -3,6 +3,7 @@ import fs from 'node:fs';
import path, { dirname } from 'node:path';
import { setTimeout as sleep } from 'node:timers/promises';
import { fileURLToPath } from 'node:url';
import { createWorkflowUrl } from '@workflow/utils';
import { createVercelWorld } from '@workflow/world-vercel';
import { onTestFailed } from 'vitest';
import { getTrustedSourcesHeaders } from '../../../scripts/trusted-sources-headers.mjs';
Expand DownExpand Up@@ -373,7 +374,7 @@ export async function fetchManifest(
 const forceRefresh = options?.forceRefresh ?? false;
 if (cachedManifest && !forceRefresh) return cachedManifest;

 const url = new URL('/.well-known/workflow/v1/manifest.json', deploymentUrl);
 const url = createWorkflowUrl(deploymentUrl, { type: 'manifest' });
 const res = await fetch(url, {
 headers: await getTrustedSourcesHeaders(),
 });
Expand Down

4 changes: 2 additions & 2 deletions
packages/core/src/create-hook.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -167,8 +167,8 @@ export interface HookOptions {
 * Whether this hook can be resumed via the public webhook endpoint.
 *
 * When `true`, the hook can be triggered by sending an HTTP request to the
 * public `/.well-known/workflow/v1/webhook/{token}` URL. This is automatically
 * set when using `createWebhook()`.
 * public workflowwebhook URL. This is automatically set when using
 * `createWebhook()`.
 *
 * When `false` (the default), the hook can only be resumed server-side
 * via `resumeHook()`.
Expand Down

9 changes: 8 additions & 1 deletion
packages/core/src/runtime.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -9,6 +9,7 @@ import {
 RunExpiredError,
 WorkflowRuntimeError,
} from '@workflow/errors';
import { setWorkflowBasePath } from '@workflow/utils';
import {
 parseWorkflowName,
 workflowDisplayName,
Expand DownExpand Up@@ -293,8 +294,14 @@ function hasOpenHookOrWait(events: Event[]): boolean {
 */
export function workflowEntrypoint(
 workflowCode: string,
 options?: { namespace?: string; routeModuleBodyStartedAt?: number }
 options?: {
 namespace?: string;
 routeModuleBodyStartedAt?: number;
 basePath?: string;
 }
): (req: Request) => Promise<Response> {
 setWorkflowBasePath(options?.basePath);

 const NO_INLINE_REPLAY_AFTER_MS =
 Number(process.env.WORKFLOW_V2_TIMEOUT_MS) || 120_000;

Expand Down
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Strip utm_, fbclid, gclid, etc. from all links on page
(function() {
var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',
'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid',
'ref', 'ref_src', 'source', 'medium', 'campaign'];
function cleanUrl(url) {
try {
var u = new URL(url, window.location.origin);
var changed = false;
trackingParams.forEach(function(p) {
if (u.searchParams.has(p)) {
u.searchParams.delete(p);
changed = true;
}
});
return changed ? u.toString() : url;
} catch (e) {
return url;
}
}
function cleanLinks() {
document.querySelectorAll('a[href]').forEach(function(a) {
var clean = cleanUrl(a.href);
if (clean !== a.href) a.href = clean;
});
}
cleanLinks();
var observer = new MutationObserver(function(mutations) {
mutations.forEach(function(m) {
m.addedNodes.forEach(function(node) {
if (node.nodeType === 1) {
if (node.tagName === 'A') cleanLinks();
node.querySelectorAll('a[href]').forEach(function(a) {
var clean = cleanUrl(a.href);
if (clean !== a.href) a.href = clean;
});
}
});
});
});
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); }
})();
(function(){
try {
var __m = "youtube.com";
var __re = new RegExp('^' + "youtube\\.com" + '
fix(next): respect basePath for workflow routes by NathanColosimo · Pull Request #2732 · vercel/workflow · GitHub
Skip to content
fix(next): respect basePath for workflow routes#2732

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

NathanColosimo
merged 9 commits into

from

Jul 6, 2026
 Merged


fix(next): respect basePath for workflow routes
#2732
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


9 commits


Select commit
Hold shift + click to select a range
7b44046

fix(next): respect basePath for workflow routes


NathanColosimo Jul 2, 2026
d06c57f

docs(core): note workflow URL resolution gap


NathanColosimo Jul 2, 2026
610c9c0

fix(next): expose workflow health route methods


NathanColosimo Jul 2, 2026
18a9a2d

test(utils): remove workflow route helper tests


NathanColosimo Jul 2, 2026
0017fca

test(builders): remove route handler string test


NathanColosimo Jul 2, 2026
cbbd394

fix(next): defer basePath validation to Next.js


NathanColosimo Jul 2, 2026
e157fba

refactor(utils): remove workflow url helper wrappers


NathanColosimo Jul 2, 2026
4fb7f19

Test Next basePath builder wiring


NathanColosimo Jul 6, 2026
ce1ddb2

Merge remote-tracking branch 'origin/main' into nathanc/fix-next-base…


NathanColosimo Jul 6, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


10 changes: 10 additions & 0 deletions
.changeset/next-base-path.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
---
"@workflow/builders": patch
"@workflow/core": patch
"@workflow/next": patch
"@workflow/utils": patch
"@workflow/world-local": patch
"@workflow/world-postgres": patch
---

Respect framework base paths when routing workflow traffic and expose health checks on generated Next.js workflow routes.

14 changes: 10 additions & 4 deletions
packages/builders/src/base-builder.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -23,7 +23,10 @@ import {
 applySwcTransform,
 type WorkflowManifest,
} from './apply-swc-transform.js';
import { createWorkflowEntrypointOptionsCode } from './constants.js';
import {
 createWorkflowEntrypointOptionsCode,
 createWorkflowRouteHandlersCode,
} from './constants.js';
import { getEsbuildTsconfigOptions } from './esbuild-tsconfig.js';
import {
 type DiscoveredEntries,
Expand DownExpand Up@@ -1564,6 +1567,7 @@ export const __steps_registered = true;

 const workflowEntrypointOptionsCode = createWorkflowEntrypointOptionsCode(
 {
 basePath: this.config.basePath,
 routeModuleBodyStartedAt: 'workflowRouteModuleBodyStartedAt',
 }
 );
Expand All@@ -1578,7 +1582,7 @@ import { workflowEntrypoint } from 'workflow/runtime';
const workflowRouteModuleBodyStartedAt = Date.now();
const workflowCode = \`${workflowBundleCode.replace(/[\\`$]/g, '\\$&')}\`;

export const POST = workflowEntrypoint(workflowCode${workflowEntrypointOptionsCode});`;
${createWorkflowRouteHandlersCode(`workflowEntrypoint(workflowCode${workflowEntrypointOptionsCode})`)}`;

 // we skip the final bundling step for Next.js so it can bundle itself
 if (!bundleFinalOutput) {
Expand DownExpand Up@@ -1771,6 +1775,7 @@ export const POST = workflowEntrypoint(workflowCode${workflowEntrypointOptionsCo
 const stepsRelativePath = `./${basename(stepsOutfile).replace(/\\/g, '/')}`;
 const escapedVMCode = workflowVMCode.replace(/[\\`$]/g, '\\$&');
 const workflowEntrypointOptionsCode = createWorkflowEntrypointOptionsCode({
 basePath: this.config.basePath,
 routeModuleBodyStartedAt: 'workflowRouteModuleBodyStartedAt',
 });

Expand All@@ -1786,7 +1791,7 @@ void __steps_registered;

const workflowCode = \`${escapedVMCode}\`;

export const POST = workflowEntrypoint(workflowCode${workflowEntrypointOptionsCode});`;
${createWorkflowRouteHandlersCode(`workflowEntrypoint(workflowCode${workflowEntrypointOptionsCode})`)}`;

 if (!bundleFinalOutput) {
 await this.writeGeneratedFile(flowOutfile, combinedFunctionCode);
Expand DownExpand Up@@ -1849,6 +1854,7 @@ export const POST = workflowEntrypoint(workflowCode${workflowEntrypointOptionsCo
 const escaped = interimBundleText.replace(/[\\`$]/g, '\\$&');
 const workflowEntrypointOptionsCode = createWorkflowEntrypointOptionsCode(
 {
 basePath: this.config.basePath,
 routeModuleBodyStartedAt: 'workflowRouteModuleBodyStartedAt',
 }
 );
Expand All@@ -1864,7 +1870,7 @@ void __steps_registered;

const workflowCode = \`${escaped}\`;

export const POST = workflowEntrypoint(workflowCode${workflowEntrypointOptionsCode});`;
${createWorkflowRouteHandlersCode(`workflowEntrypoint(workflowCode${workflowEntrypointOptionsCode})`)}`;

 const outputDir = dirname(flowOutfile);
 await mkdir(outputDir, { recursive: true });
Expand Down

3 changes: 2 additions & 1 deletion
packages/builders/src/constants.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -53,10 +53,11 @@ describe('createWorkflowEntrypointOptionsCode', () => {
 expect(
 createWorkflowEntrypointOptionsCode({
 namespace: 'custom',
 basePath: '/v2',
 routeModuleBodyStartedAt: 'workflowRouteModuleBodyStartedAt',
 })
 ).toBe(
 ', { namespace: "custom", routeModuleBodyStartedAt: workflowRouteModuleBodyStartedAt }'
 ', { namespace: "custom", basePath: "/v2", routeModuleBodyStartedAt: workflowRouteModuleBodyStartedAt }'
 );
 });
});

14 changes: 14 additions & 0 deletions
packages/builders/src/constants.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -54,6 +54,7 @@ export function createWorkflowQueueTrigger(options?: { namespace?: string }) {
 */
export function createWorkflowEntrypointOptionsCode(options?: {
 namespace?: string;
 basePath?: string;
 /** Raw code identifier/expression emitted into generated route files, not data. */
 routeModuleBodyStartedAt?: string;
}) {
Expand All@@ -66,6 +67,10 @@ export function createWorkflowEntrypointOptionsCode(options?: {
 fields.push(`namespace: ${JSON.stringify(namespace)}`);
 }

 if (options?.basePath !== undefined) {
 fields.push(`basePath: ${JSON.stringify(options.basePath)}`);
 }

 if (options?.routeModuleBodyStartedAt) {
 fields.push(
 `routeModuleBodyStartedAt: ${options.routeModuleBodyStartedAt}`
Expand All@@ -79,6 +84,15 @@ export function createWorkflowEntrypointOptionsCode(options?: {
 return `, { ${fields.join(', ')} }`;
}

export function createWorkflowRouteHandlersCode(
 workflowEntrypointCall: string
) {
 return `export const POST = ${workflowEntrypointCall};
export const GET = POST;
export const HEAD = POST;
export const OPTIONS = POST;`;
}

/**
 * Default queue trigger (no namespace). Backward compatible.
 */
Expand Down

3 changes: 3 additions & 0 deletions
packages/builders/src/types.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -60,6 +60,9 @@ interface BaseWorkflowConfig {
 // artifact locations.
 distDir?: string;

 // Optional route prefix for apps deployed below the origin root.
 basePath?: string;

 // Suppress informational logs emitted by createWorkflowsBundle()
 // (e.g. intermediate/final workflow bundle timing logs).
 suppressCreateWorkflowsBundleLogs?: boolean;
Expand Down

124 changes: 39 additions & 85 deletions
packages/core/e2e/e2e.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -10,6 +10,7 @@ import {
 WorkflowRunFailedError,
 WorkflowWorldError,
} from '@workflow/errors';
import { createWorkflowUrl } from '@workflow/utils';
import { SPEC_VERSION_CURRENT, type World } from '@workflow/world';
import {
 afterAll,
Expand DownExpand Up@@ -111,6 +112,9 @@ function writeE2EMetadata() {
const e2e = (fn: string) =>
 getWorkflowMetadata(deploymentUrl, 'workflows/99_e2e.ts', fn);

const workflowWebhookUrl = (token: string) =>
 createWorkflowUrl(deploymentUrl, { type: 'webhook', token });

type WorkflowEvent = Awaited<
 ReturnType<World['events']['list']>
>['data'][number];
Expand DownExpand Up@@ -532,17 +536,11 @@ describe('e2e', () => {
 expect(hook.runId).toBe(run.runId);

 // Attempt to resume via the public webhook endpoint — should get 404
 const res = await fetch(
 new URL(
 `/.well-known/workflow/v1/webhook/${encodeURIComponent(token)}`,
 deploymentUrl
 ),
 {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: JSON.stringify({ message: 'should-be-rejected' }),
 }
 );
 const res = await fetch(workflowWebhookUrl(token), {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: JSON.stringify({ message: 'should-be-rejected' }),
 });
 expect(res.status).toBe(404);

 // Now resume via server-side resumeHook() — should work
Expand DownExpand Up@@ -587,79 +585,46 @@ describe('e2e', () => {
 const [token, token2, token3] = hooks.map((h) => h.token);

 // Webhook with default response
 const res = await fetch(
 new URL(
 `/.well-known/workflow/v1/webhook/${encodeURIComponent(token)}`,
 deploymentUrl
 ),
 {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: JSON.stringify({ message: 'one' }),
 }
 );
 const res = await fetch(workflowWebhookUrl(token), {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: JSON.stringify({ message: 'one' }),
 });
 expect(res.status).toBe(202);
 const body = await res.text();
 expect(body).toBe('');

 // Webhook with static response
 const res2 = await fetch(
 new URL(
 `/.well-known/workflow/v1/webhook/${encodeURIComponent(token2)}`,
 deploymentUrl
 ),
 {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: JSON.stringify({ message: 'two' }),
 }
 );
 const res2 = await fetch(workflowWebhookUrl(token2), {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: JSON.stringify({ message: 'two' }),
 });
 expect(res2.status).toBe(402);
 const body2 = await res2.text();
 expect(body2).toBe('Hello from static response!');

 // Webhook with manual response
 const res3 = await fetch(
 new URL(
 `/.well-known/workflow/v1/webhook/${encodeURIComponent(token3)}`,
 deploymentUrl
 ),
 {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: JSON.stringify({ message: 'three' }),
 }
 );
 const res3 = await fetch(workflowWebhookUrl(token3), {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: JSON.stringify({ message: 'three' }),
 });
 expect(res3.status).toBe(200);
 const body3 = await res3.text();
 expect(body3).toBe('Hello from webhook!');

 const returnValue = await run.returnValue;
 expect(returnValue).toHaveLength(3);
 expect(returnValue[0].url).toBe(
 new URL(
 `/.well-known/workflow/v1/webhook/${encodeURIComponent(token)}`,
 deploymentUrl
 ).href
 );
 expect(returnValue[0].url).toBe(workflowWebhookUrl(token));
 expect(returnValue[0].method).toBe('POST');
 expect(returnValue[0].body).toBe('{"message":"one"}');

 expect(returnValue[1].url).toBe(
 new URL(
 `/.well-known/workflow/v1/webhook/${encodeURIComponent(token2)}`,
 deploymentUrl
 ).href
 );
 expect(returnValue[1].url).toBe(workflowWebhookUrl(token2));
 expect(returnValue[1].method).toBe('POST');
 expect(returnValue[1].body).toBe('{"message":"two"}');

 expect(returnValue[2].url).toBe(
 new URL(
 `/.well-known/workflow/v1/webhook/${encodeURIComponent(token3)}`,
 deploymentUrl
 ).href
 );
 expect(returnValue[2].url).toBe(workflowWebhookUrl(token3));
 expect(returnValue[2].method).toBe('POST');
 expect(returnValue[2].body).toBe('{"message":"three"}');
 });
Expand DownExpand Up@@ -730,17 +695,11 @@ describe('e2e', () => {
 continue;
 }

 const res = await fetch(
 new URL(
 `/.well-known/workflow/v1/webhook/${encodeURIComponent(unservedHook.token)}`,
 deploymentUrl
 ),
 {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: `body-${unservedHook.token}`,
 }
 );
 const res = await fetch(workflowWebhookUrl(unservedHook.token), {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: `body-${unservedHook.token}`,
 });
 expect(res.status).toBe(202);
 servedTokens.add(unservedHook.token);
 }
Expand DownExpand Up@@ -786,11 +745,7 @@ describe('e2e', () => {
 );

 test('webhook route with invalid token', { timeout: 60_000 }, async () => {
 const invalidWebhookUrl = new URL(
 `/.well-known/workflow/v1/webhook/${encodeURIComponent('invalid')}`,
 deploymentUrl
 );
 const res = await fetch(invalidWebhookUrl, {
 const res = await fetch(workflowWebhookUrl('invalid'), {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: JSON.stringify({}),
Expand DownExpand Up@@ -2555,14 +2510,13 @@ describe('e2e', () => {
 // bypasses protection by sending messages through the Queue infrastructure.

 // Test the flow endpoint health check (V2: combined handler for both workflow + step)
 const flowHealthUrl = new URL(
 '/.well-known/workflow/v1/flow?__health',
 deploymentUrl
 const flowRes = await fetch(
 createWorkflowUrl(deploymentUrl, { type: 'health' }),
 {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 }
 );
 const flowRes = await fetch(flowHealthUrl, {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 });
 expect(flowRes.status).toBe(200);
 expect(flowRes.headers.get('Content-Type')).toBe('application/json');
 const flowBody = await flowRes.json();
Expand Down

3 changes: 2 additions & 1 deletion
packages/core/e2e/utils.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -3,6 +3,7 @@ import fs from 'node:fs';
import path, { dirname } from 'node:path';
import { setTimeout as sleep } from 'node:timers/promises';
import { fileURLToPath } from 'node:url';
import { createWorkflowUrl } from '@workflow/utils';
import { createVercelWorld } from '@workflow/world-vercel';
import { onTestFailed } from 'vitest';
import { getTrustedSourcesHeaders } from '../../../scripts/trusted-sources-headers.mjs';
Expand DownExpand Up@@ -373,7 +374,7 @@ export async function fetchManifest(
 const forceRefresh = options?.forceRefresh ?? false;
 if (cachedManifest && !forceRefresh) return cachedManifest;

 const url = new URL('/.well-known/workflow/v1/manifest.json', deploymentUrl);
 const url = createWorkflowUrl(deploymentUrl, { type: 'manifest' });
 const res = await fetch(url, {
 headers: await getTrustedSourcesHeaders(),
 });
Expand Down

4 changes: 2 additions & 2 deletions
packages/core/src/create-hook.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -167,8 +167,8 @@ export interface HookOptions {
 * Whether this hook can be resumed via the public webhook endpoint.
 *
 * When `true`, the hook can be triggered by sending an HTTP request to the
 * public `/.well-known/workflow/v1/webhook/{token}` URL. This is automatically
 * set when using `createWebhook()`.
 * public workflowwebhook URL. This is automatically set when using
 * `createWebhook()`.
 *
 * When `false` (the default), the hook can only be resumed server-side
 * via `resumeHook()`.
Expand Down

9 changes: 8 additions & 1 deletion
packages/core/src/runtime.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -9,6 +9,7 @@ import {
 RunExpiredError,
 WorkflowRuntimeError,
} from '@workflow/errors';
import { setWorkflowBasePath } from '@workflow/utils';
import {
 parseWorkflowName,
 workflowDisplayName,
Expand DownExpand Up@@ -293,8 +294,14 @@ function hasOpenHookOrWait(events: Event[]): boolean {
 */
export function workflowEntrypoint(
 workflowCode: string,
 options?: { namespace?: string; routeModuleBodyStartedAt?: number }
 options?: {
 namespace?: string;
 routeModuleBodyStartedAt?: number;
 basePath?: string;
 }
): (req: Request) => Promise<Response> {
 setWorkflowBasePath(options?.basePath);

 const NO_INLINE_REPLAY_AFTER_MS =
 Number(process.env.WORKFLOW_V2_TIMEOUT_MS) || 120_000;

Expand Down
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Auto-enable theater mode on YouTube
(function() {
function tryTheater() {
var btn = document.querySelector('button[aria-label="Theater mode"], ytd-player #player button[title="Theater mode"]');
if (btn && !btn.classList.contains('activated')) {
btn.click();
}
}
// Try immediately
tryTheater();
// Try after navigation (SPA)
var lastUrl = location.href;
setInterval(function() {
if (location.href !== lastUrl) {
lastUrl = location.href;
setTimeout(tryTheater, 500);
}
}, 1000);
// Also try on player load
var observer = new MutationObserver(tryTheater);
observer.observe(document.body, { childList: true, subtree: true });
})();
}
} catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '
fix(next): respect basePath for workflow routes by NathanColosimo · Pull Request #2732 · vercel/workflow · GitHub
Skip to content
fix(next): respect basePath for workflow routes#2732

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

NathanColosimo
merged 9 commits into

from

Jul 6, 2026
 Merged


fix(next): respect basePath for workflow routes
#2732
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


9 commits


Select commit
Hold shift + click to select a range
7b44046

fix(next): respect basePath for workflow routes


NathanColosimo Jul 2, 2026
d06c57f

docs(core): note workflow URL resolution gap


NathanColosimo Jul 2, 2026
610c9c0

fix(next): expose workflow health route methods


NathanColosimo Jul 2, 2026
18a9a2d

test(utils): remove workflow route helper tests


NathanColosimo Jul 2, 2026
0017fca

test(builders): remove route handler string test


NathanColosimo Jul 2, 2026
cbbd394

fix(next): defer basePath validation to Next.js


NathanColosimo Jul 2, 2026
e157fba

refactor(utils): remove workflow url helper wrappers


NathanColosimo Jul 2, 2026
4fb7f19

Test Next basePath builder wiring


NathanColosimo Jul 6, 2026
ce1ddb2

Merge remote-tracking branch 'origin/main' into nathanc/fix-next-base…


NathanColosimo Jul 6, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


10 changes: 10 additions & 0 deletions
.changeset/next-base-path.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
---
"@workflow/builders": patch
"@workflow/core": patch
"@workflow/next": patch
"@workflow/utils": patch
"@workflow/world-local": patch
"@workflow/world-postgres": patch
---

Respect framework base paths when routing workflow traffic and expose health checks on generated Next.js workflow routes.

14 changes: 10 additions & 4 deletions
packages/builders/src/base-builder.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -23,7 +23,10 @@ import {
 applySwcTransform,
 type WorkflowManifest,
} from './apply-swc-transform.js';
import { createWorkflowEntrypointOptionsCode } from './constants.js';
import {
 createWorkflowEntrypointOptionsCode,
 createWorkflowRouteHandlersCode,
} from './constants.js';
import { getEsbuildTsconfigOptions } from './esbuild-tsconfig.js';
import {
 type DiscoveredEntries,
Expand DownExpand Up@@ -1564,6 +1567,7 @@ export const __steps_registered = true;

 const workflowEntrypointOptionsCode = createWorkflowEntrypointOptionsCode(
 {
 basePath: this.config.basePath,
 routeModuleBodyStartedAt: 'workflowRouteModuleBodyStartedAt',
 }
 );
Expand All@@ -1578,7 +1582,7 @@ import { workflowEntrypoint } from 'workflow/runtime';
const workflowRouteModuleBodyStartedAt = Date.now();
const workflowCode = \`${workflowBundleCode.replace(/[\\`$]/g, '\\$&')}\`;

export const POST = workflowEntrypoint(workflowCode${workflowEntrypointOptionsCode});`;
${createWorkflowRouteHandlersCode(`workflowEntrypoint(workflowCode${workflowEntrypointOptionsCode})`)}`;

 // we skip the final bundling step for Next.js so it can bundle itself
 if (!bundleFinalOutput) {
Expand DownExpand Up@@ -1771,6 +1775,7 @@ export const POST = workflowEntrypoint(workflowCode${workflowEntrypointOptionsCo
 const stepsRelativePath = `./${basename(stepsOutfile).replace(/\\/g, '/')}`;
 const escapedVMCode = workflowVMCode.replace(/[\\`$]/g, '\\$&');
 const workflowEntrypointOptionsCode = createWorkflowEntrypointOptionsCode({
 basePath: this.config.basePath,
 routeModuleBodyStartedAt: 'workflowRouteModuleBodyStartedAt',
 });

Expand All@@ -1786,7 +1791,7 @@ void __steps_registered;

const workflowCode = \`${escapedVMCode}\`;

export const POST = workflowEntrypoint(workflowCode${workflowEntrypointOptionsCode});`;
${createWorkflowRouteHandlersCode(`workflowEntrypoint(workflowCode${workflowEntrypointOptionsCode})`)}`;

 if (!bundleFinalOutput) {
 await this.writeGeneratedFile(flowOutfile, combinedFunctionCode);
Expand DownExpand Up@@ -1849,6 +1854,7 @@ export const POST = workflowEntrypoint(workflowCode${workflowEntrypointOptionsCo
 const escaped = interimBundleText.replace(/[\\`$]/g, '\\$&');
 const workflowEntrypointOptionsCode = createWorkflowEntrypointOptionsCode(
 {
 basePath: this.config.basePath,
 routeModuleBodyStartedAt: 'workflowRouteModuleBodyStartedAt',
 }
 );
Expand All@@ -1864,7 +1870,7 @@ void __steps_registered;

const workflowCode = \`${escaped}\`;

export const POST = workflowEntrypoint(workflowCode${workflowEntrypointOptionsCode});`;
${createWorkflowRouteHandlersCode(`workflowEntrypoint(workflowCode${workflowEntrypointOptionsCode})`)}`;

 const outputDir = dirname(flowOutfile);
 await mkdir(outputDir, { recursive: true });
Expand Down

3 changes: 2 additions & 1 deletion
packages/builders/src/constants.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -53,10 +53,11 @@ describe('createWorkflowEntrypointOptionsCode', () => {
 expect(
 createWorkflowEntrypointOptionsCode({
 namespace: 'custom',
 basePath: '/v2',
 routeModuleBodyStartedAt: 'workflowRouteModuleBodyStartedAt',
 })
 ).toBe(
 ', { namespace: "custom", routeModuleBodyStartedAt: workflowRouteModuleBodyStartedAt }'
 ', { namespace: "custom", basePath: "/v2", routeModuleBodyStartedAt: workflowRouteModuleBodyStartedAt }'
 );
 });
});

14 changes: 14 additions & 0 deletions
packages/builders/src/constants.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -54,6 +54,7 @@ export function createWorkflowQueueTrigger(options?: { namespace?: string }) {
 */
export function createWorkflowEntrypointOptionsCode(options?: {
 namespace?: string;
 basePath?: string;
 /** Raw code identifier/expression emitted into generated route files, not data. */
 routeModuleBodyStartedAt?: string;
}) {
Expand All@@ -66,6 +67,10 @@ export function createWorkflowEntrypointOptionsCode(options?: {
 fields.push(`namespace: ${JSON.stringify(namespace)}`);
 }

 if (options?.basePath !== undefined) {
 fields.push(`basePath: ${JSON.stringify(options.basePath)}`);
 }

 if (options?.routeModuleBodyStartedAt) {
 fields.push(
 `routeModuleBodyStartedAt: ${options.routeModuleBodyStartedAt}`
Expand All@@ -79,6 +84,15 @@ export function createWorkflowEntrypointOptionsCode(options?: {
 return `, { ${fields.join(', ')} }`;
}

export function createWorkflowRouteHandlersCode(
 workflowEntrypointCall: string
) {
 return `export const POST = ${workflowEntrypointCall};
export const GET = POST;
export const HEAD = POST;
export const OPTIONS = POST;`;
}

/**
 * Default queue trigger (no namespace). Backward compatible.
 */
Expand Down

3 changes: 3 additions & 0 deletions
packages/builders/src/types.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -60,6 +60,9 @@ interface BaseWorkflowConfig {
 // artifact locations.
 distDir?: string;

 // Optional route prefix for apps deployed below the origin root.
 basePath?: string;

 // Suppress informational logs emitted by createWorkflowsBundle()
 // (e.g. intermediate/final workflow bundle timing logs).
 suppressCreateWorkflowsBundleLogs?: boolean;
Expand Down

124 changes: 39 additions & 85 deletions
packages/core/e2e/e2e.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -10,6 +10,7 @@ import {
 WorkflowRunFailedError,
 WorkflowWorldError,
} from '@workflow/errors';
import { createWorkflowUrl } from '@workflow/utils';
import { SPEC_VERSION_CURRENT, type World } from '@workflow/world';
import {
 afterAll,
Expand DownExpand Up@@ -111,6 +112,9 @@ function writeE2EMetadata() {
const e2e = (fn: string) =>
 getWorkflowMetadata(deploymentUrl, 'workflows/99_e2e.ts', fn);

const workflowWebhookUrl = (token: string) =>
 createWorkflowUrl(deploymentUrl, { type: 'webhook', token });

type WorkflowEvent = Awaited<
 ReturnType<World['events']['list']>
>['data'][number];
Expand DownExpand Up@@ -532,17 +536,11 @@ describe('e2e', () => {
 expect(hook.runId).toBe(run.runId);

 // Attempt to resume via the public webhook endpoint — should get 404
 const res = await fetch(
 new URL(
 `/.well-known/workflow/v1/webhook/${encodeURIComponent(token)}`,
 deploymentUrl
 ),
 {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: JSON.stringify({ message: 'should-be-rejected' }),
 }
 );
 const res = await fetch(workflowWebhookUrl(token), {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: JSON.stringify({ message: 'should-be-rejected' }),
 });
 expect(res.status).toBe(404);

 // Now resume via server-side resumeHook() — should work
Expand DownExpand Up@@ -587,79 +585,46 @@ describe('e2e', () => {
 const [token, token2, token3] = hooks.map((h) => h.token);

 // Webhook with default response
 const res = await fetch(
 new URL(
 `/.well-known/workflow/v1/webhook/${encodeURIComponent(token)}`,
 deploymentUrl
 ),
 {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: JSON.stringify({ message: 'one' }),
 }
 );
 const res = await fetch(workflowWebhookUrl(token), {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: JSON.stringify({ message: 'one' }),
 });
 expect(res.status).toBe(202);
 const body = await res.text();
 expect(body).toBe('');

 // Webhook with static response
 const res2 = await fetch(
 new URL(
 `/.well-known/workflow/v1/webhook/${encodeURIComponent(token2)}`,
 deploymentUrl
 ),
 {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: JSON.stringify({ message: 'two' }),
 }
 );
 const res2 = await fetch(workflowWebhookUrl(token2), {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: JSON.stringify({ message: 'two' }),
 });
 expect(res2.status).toBe(402);
 const body2 = await res2.text();
 expect(body2).toBe('Hello from static response!');

 // Webhook with manual response
 const res3 = await fetch(
 new URL(
 `/.well-known/workflow/v1/webhook/${encodeURIComponent(token3)}`,
 deploymentUrl
 ),
 {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: JSON.stringify({ message: 'three' }),
 }
 );
 const res3 = await fetch(workflowWebhookUrl(token3), {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: JSON.stringify({ message: 'three' }),
 });
 expect(res3.status).toBe(200);
 const body3 = await res3.text();
 expect(body3).toBe('Hello from webhook!');

 const returnValue = await run.returnValue;
 expect(returnValue).toHaveLength(3);
 expect(returnValue[0].url).toBe(
 new URL(
 `/.well-known/workflow/v1/webhook/${encodeURIComponent(token)}`,
 deploymentUrl
 ).href
 );
 expect(returnValue[0].url).toBe(workflowWebhookUrl(token));
 expect(returnValue[0].method).toBe('POST');
 expect(returnValue[0].body).toBe('{"message":"one"}');

 expect(returnValue[1].url).toBe(
 new URL(
 `/.well-known/workflow/v1/webhook/${encodeURIComponent(token2)}`,
 deploymentUrl
 ).href
 );
 expect(returnValue[1].url).toBe(workflowWebhookUrl(token2));
 expect(returnValue[1].method).toBe('POST');
 expect(returnValue[1].body).toBe('{"message":"two"}');

 expect(returnValue[2].url).toBe(
 new URL(
 `/.well-known/workflow/v1/webhook/${encodeURIComponent(token3)}`,
 deploymentUrl
 ).href
 );
 expect(returnValue[2].url).toBe(workflowWebhookUrl(token3));
 expect(returnValue[2].method).toBe('POST');
 expect(returnValue[2].body).toBe('{"message":"three"}');
 });
Expand DownExpand Up@@ -730,17 +695,11 @@ describe('e2e', () => {
 continue;
 }

 const res = await fetch(
 new URL(
 `/.well-known/workflow/v1/webhook/${encodeURIComponent(unservedHook.token)}`,
 deploymentUrl
 ),
 {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: `body-${unservedHook.token}`,
 }
 );
 const res = await fetch(workflowWebhookUrl(unservedHook.token), {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: `body-${unservedHook.token}`,
 });
 expect(res.status).toBe(202);
 servedTokens.add(unservedHook.token);
 }
Expand DownExpand Up@@ -786,11 +745,7 @@ describe('e2e', () => {
 );

 test('webhook route with invalid token', { timeout: 60_000 }, async () => {
 const invalidWebhookUrl = new URL(
 `/.well-known/workflow/v1/webhook/${encodeURIComponent('invalid')}`,
 deploymentUrl
 );
 const res = await fetch(invalidWebhookUrl, {
 const res = await fetch(workflowWebhookUrl('invalid'), {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: JSON.stringify({}),
Expand DownExpand Up@@ -2555,14 +2510,13 @@ describe('e2e', () => {
 // bypasses protection by sending messages through the Queue infrastructure.

 // Test the flow endpoint health check (V2: combined handler for both workflow + step)
 const flowHealthUrl = new URL(
 '/.well-known/workflow/v1/flow?__health',
 deploymentUrl
 const flowRes = await fetch(
 createWorkflowUrl(deploymentUrl, { type: 'health' }),
 {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 }
 );
 const flowRes = await fetch(flowHealthUrl, {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 });
 expect(flowRes.status).toBe(200);
 expect(flowRes.headers.get('Content-Type')).toBe('application/json');
 const flowBody = await flowRes.json();
Expand Down

3 changes: 2 additions & 1 deletion
packages/core/e2e/utils.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -3,6 +3,7 @@ import fs from 'node:fs';
import path, { dirname } from 'node:path';
import { setTimeout as sleep } from 'node:timers/promises';
import { fileURLToPath } from 'node:url';
import { createWorkflowUrl } from '@workflow/utils';
import { createVercelWorld } from '@workflow/world-vercel';
import { onTestFailed } from 'vitest';
import { getTrustedSourcesHeaders } from '../../../scripts/trusted-sources-headers.mjs';
Expand DownExpand Up@@ -373,7 +374,7 @@ export async function fetchManifest(
 const forceRefresh = options?.forceRefresh ?? false;
 if (cachedManifest && !forceRefresh) return cachedManifest;

 const url = new URL('/.well-known/workflow/v1/manifest.json', deploymentUrl);
 const url = createWorkflowUrl(deploymentUrl, { type: 'manifest' });
 const res = await fetch(url, {
 headers: await getTrustedSourcesHeaders(),
 });
Expand Down

4 changes: 2 additions & 2 deletions
packages/core/src/create-hook.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -167,8 +167,8 @@ export interface HookOptions {
 * Whether this hook can be resumed via the public webhook endpoint.
 *
 * When `true`, the hook can be triggered by sending an HTTP request to the
 * public `/.well-known/workflow/v1/webhook/{token}` URL. This is automatically
 * set when using `createWebhook()`.
 * public workflowwebhook URL. This is automatically set when using
 * `createWebhook()`.
 *
 * When `false` (the default), the hook can only be resumed server-side
 * via `resumeHook()`.
Expand Down

9 changes: 8 additions & 1 deletion
packages/core/src/runtime.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -9,6 +9,7 @@ import {
 RunExpiredError,
 WorkflowRuntimeError,
} from '@workflow/errors';
import { setWorkflowBasePath } from '@workflow/utils';
import {
 parseWorkflowName,
 workflowDisplayName,
Expand DownExpand Up@@ -293,8 +294,14 @@ function hasOpenHookOrWait(events: Event[]): boolean {
 */
export function workflowEntrypoint(
 workflowCode: string,
 options?: { namespace?: string; routeModuleBodyStartedAt?: number }
 options?: {
 namespace?: string;
 routeModuleBodyStartedAt?: number;
 basePath?: string;
 }
): (req: Request) => Promise<Response> {
 setWorkflowBasePath(options?.basePath);

 const NO_INLINE_REPLAY_AFTER_MS =
 Number(process.env.WORKFLOW_V2_TIMEOUT_MS) || 120_000;

Expand Down
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Remove or un-stick sticky/fixed headers that block content
(function() {
function unstick() {
document.querySelectorAll('header, nav, [role="banner"], .header, .navbar, .sticky, .fixed-top, [style*="position: fixed"], [style*="position:sticky"]').forEach(function(el) {
if (el.style.position === 'fixed' || el.style.position === 'sticky' || getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') {
el.style.position = 'static';
el.style.top = 'auto';
el.style.zIndex = 'auto';
}
});
}
unstick();
var observer = new MutationObserver(unstick);
observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] });
})();
}
} catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '
fix(next): respect basePath for workflow routes by NathanColosimo · Pull Request #2732 · vercel/workflow · GitHub
Skip to content
fix(next): respect basePath for workflow routes#2732

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

NathanColosimo
merged 9 commits into

from

Jul 6, 2026
 Merged


fix(next): respect basePath for workflow routes
#2732
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


9 commits


Select commit
Hold shift + click to select a range
7b44046

fix(next): respect basePath for workflow routes


NathanColosimo Jul 2, 2026
d06c57f

docs(core): note workflow URL resolution gap


NathanColosimo Jul 2, 2026
610c9c0

fix(next): expose workflow health route methods


NathanColosimo Jul 2, 2026
18a9a2d

test(utils): remove workflow route helper tests


NathanColosimo Jul 2, 2026
0017fca

test(builders): remove route handler string test


NathanColosimo Jul 2, 2026
cbbd394

fix(next): defer basePath validation to Next.js


NathanColosimo Jul 2, 2026
e157fba

refactor(utils): remove workflow url helper wrappers


NathanColosimo Jul 2, 2026
4fb7f19

Test Next basePath builder wiring


NathanColosimo Jul 6, 2026
ce1ddb2

Merge remote-tracking branch 'origin/main' into nathanc/fix-next-base…


NathanColosimo Jul 6, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


10 changes: 10 additions & 0 deletions
.changeset/next-base-path.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
---
"@workflow/builders": patch
"@workflow/core": patch
"@workflow/next": patch
"@workflow/utils": patch
"@workflow/world-local": patch
"@workflow/world-postgres": patch
---

Respect framework base paths when routing workflow traffic and expose health checks on generated Next.js workflow routes.

14 changes: 10 additions & 4 deletions
packages/builders/src/base-builder.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -23,7 +23,10 @@ import {
 applySwcTransform,
 type WorkflowManifest,
} from './apply-swc-transform.js';
import { createWorkflowEntrypointOptionsCode } from './constants.js';
import {
 createWorkflowEntrypointOptionsCode,
 createWorkflowRouteHandlersCode,
} from './constants.js';
import { getEsbuildTsconfigOptions } from './esbuild-tsconfig.js';
import {
 type DiscoveredEntries,
Expand DownExpand Up@@ -1564,6 +1567,7 @@ export const __steps_registered = true;

 const workflowEntrypointOptionsCode = createWorkflowEntrypointOptionsCode(
 {
 basePath: this.config.basePath,
 routeModuleBodyStartedAt: 'workflowRouteModuleBodyStartedAt',
 }
 );
Expand All@@ -1578,7 +1582,7 @@ import { workflowEntrypoint } from 'workflow/runtime';
const workflowRouteModuleBodyStartedAt = Date.now();
const workflowCode = \`${workflowBundleCode.replace(/[\\`$]/g, '\\$&')}\`;

export const POST = workflowEntrypoint(workflowCode${workflowEntrypointOptionsCode});`;
${createWorkflowRouteHandlersCode(`workflowEntrypoint(workflowCode${workflowEntrypointOptionsCode})`)}`;

 // we skip the final bundling step for Next.js so it can bundle itself
 if (!bundleFinalOutput) {
Expand DownExpand Up@@ -1771,6 +1775,7 @@ export const POST = workflowEntrypoint(workflowCode${workflowEntrypointOptionsCo
 const stepsRelativePath = `./${basename(stepsOutfile).replace(/\\/g, '/')}`;
 const escapedVMCode = workflowVMCode.replace(/[\\`$]/g, '\\$&');
 const workflowEntrypointOptionsCode = createWorkflowEntrypointOptionsCode({
 basePath: this.config.basePath,
 routeModuleBodyStartedAt: 'workflowRouteModuleBodyStartedAt',
 });

Expand All@@ -1786,7 +1791,7 @@ void __steps_registered;

const workflowCode = \`${escapedVMCode}\`;

export const POST = workflowEntrypoint(workflowCode${workflowEntrypointOptionsCode});`;
${createWorkflowRouteHandlersCode(`workflowEntrypoint(workflowCode${workflowEntrypointOptionsCode})`)}`;

 if (!bundleFinalOutput) {
 await this.writeGeneratedFile(flowOutfile, combinedFunctionCode);
Expand DownExpand Up@@ -1849,6 +1854,7 @@ export const POST = workflowEntrypoint(workflowCode${workflowEntrypointOptionsCo
 const escaped = interimBundleText.replace(/[\\`$]/g, '\\$&');
 const workflowEntrypointOptionsCode = createWorkflowEntrypointOptionsCode(
 {
 basePath: this.config.basePath,
 routeModuleBodyStartedAt: 'workflowRouteModuleBodyStartedAt',
 }
 );
Expand All@@ -1864,7 +1870,7 @@ void __steps_registered;

const workflowCode = \`${escaped}\`;

export const POST = workflowEntrypoint(workflowCode${workflowEntrypointOptionsCode});`;
${createWorkflowRouteHandlersCode(`workflowEntrypoint(workflowCode${workflowEntrypointOptionsCode})`)}`;

 const outputDir = dirname(flowOutfile);
 await mkdir(outputDir, { recursive: true });
Expand Down

3 changes: 2 additions & 1 deletion
packages/builders/src/constants.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -53,10 +53,11 @@ describe('createWorkflowEntrypointOptionsCode', () => {
 expect(
 createWorkflowEntrypointOptionsCode({
 namespace: 'custom',
 basePath: '/v2',
 routeModuleBodyStartedAt: 'workflowRouteModuleBodyStartedAt',
 })
 ).toBe(
 ', { namespace: "custom", routeModuleBodyStartedAt: workflowRouteModuleBodyStartedAt }'
 ', { namespace: "custom", basePath: "/v2", routeModuleBodyStartedAt: workflowRouteModuleBodyStartedAt }'
 );
 });
});

14 changes: 14 additions & 0 deletions
packages/builders/src/constants.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -54,6 +54,7 @@ export function createWorkflowQueueTrigger(options?: { namespace?: string }) {
 */
export function createWorkflowEntrypointOptionsCode(options?: {
 namespace?: string;
 basePath?: string;
 /** Raw code identifier/expression emitted into generated route files, not data. */
 routeModuleBodyStartedAt?: string;
}) {
Expand All@@ -66,6 +67,10 @@ export function createWorkflowEntrypointOptionsCode(options?: {
 fields.push(`namespace: ${JSON.stringify(namespace)}`);
 }

 if (options?.basePath !== undefined) {
 fields.push(`basePath: ${JSON.stringify(options.basePath)}`);
 }

 if (options?.routeModuleBodyStartedAt) {
 fields.push(
 `routeModuleBodyStartedAt: ${options.routeModuleBodyStartedAt}`
Expand All@@ -79,6 +84,15 @@ export function createWorkflowEntrypointOptionsCode(options?: {
 return `, { ${fields.join(', ')} }`;
}

export function createWorkflowRouteHandlersCode(
 workflowEntrypointCall: string
) {
 return `export const POST = ${workflowEntrypointCall};
export const GET = POST;
export const HEAD = POST;
export const OPTIONS = POST;`;
}

/**
 * Default queue trigger (no namespace). Backward compatible.
 */
Expand Down

3 changes: 3 additions & 0 deletions
packages/builders/src/types.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -60,6 +60,9 @@ interface BaseWorkflowConfig {
 // artifact locations.
 distDir?: string;

 // Optional route prefix for apps deployed below the origin root.
 basePath?: string;

 // Suppress informational logs emitted by createWorkflowsBundle()
 // (e.g. intermediate/final workflow bundle timing logs).
 suppressCreateWorkflowsBundleLogs?: boolean;
Expand Down

124 changes: 39 additions & 85 deletions
packages/core/e2e/e2e.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -10,6 +10,7 @@ import {
 WorkflowRunFailedError,
 WorkflowWorldError,
} from '@workflow/errors';
import { createWorkflowUrl } from '@workflow/utils';
import { SPEC_VERSION_CURRENT, type World } from '@workflow/world';
import {
 afterAll,
Expand DownExpand Up@@ -111,6 +112,9 @@ function writeE2EMetadata() {
const e2e = (fn: string) =>
 getWorkflowMetadata(deploymentUrl, 'workflows/99_e2e.ts', fn);

const workflowWebhookUrl = (token: string) =>
 createWorkflowUrl(deploymentUrl, { type: 'webhook', token });

type WorkflowEvent = Awaited<
 ReturnType<World['events']['list']>
>['data'][number];
Expand DownExpand Up@@ -532,17 +536,11 @@ describe('e2e', () => {
 expect(hook.runId).toBe(run.runId);

 // Attempt to resume via the public webhook endpoint — should get 404
 const res = await fetch(
 new URL(
 `/.well-known/workflow/v1/webhook/${encodeURIComponent(token)}`,
 deploymentUrl
 ),
 {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: JSON.stringify({ message: 'should-be-rejected' }),
 }
 );
 const res = await fetch(workflowWebhookUrl(token), {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: JSON.stringify({ message: 'should-be-rejected' }),
 });
 expect(res.status).toBe(404);

 // Now resume via server-side resumeHook() — should work
Expand DownExpand Up@@ -587,79 +585,46 @@ describe('e2e', () => {
 const [token, token2, token3] = hooks.map((h) => h.token);

 // Webhook with default response
 const res = await fetch(
 new URL(
 `/.well-known/workflow/v1/webhook/${encodeURIComponent(token)}`,
 deploymentUrl
 ),
 {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: JSON.stringify({ message: 'one' }),
 }
 );
 const res = await fetch(workflowWebhookUrl(token), {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: JSON.stringify({ message: 'one' }),
 });
 expect(res.status).toBe(202);
 const body = await res.text();
 expect(body).toBe('');

 // Webhook with static response
 const res2 = await fetch(
 new URL(
 `/.well-known/workflow/v1/webhook/${encodeURIComponent(token2)}`,
 deploymentUrl
 ),
 {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: JSON.stringify({ message: 'two' }),
 }
 );
 const res2 = await fetch(workflowWebhookUrl(token2), {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: JSON.stringify({ message: 'two' }),
 });
 expect(res2.status).toBe(402);
 const body2 = await res2.text();
 expect(body2).toBe('Hello from static response!');

 // Webhook with manual response
 const res3 = await fetch(
 new URL(
 `/.well-known/workflow/v1/webhook/${encodeURIComponent(token3)}`,
 deploymentUrl
 ),
 {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: JSON.stringify({ message: 'three' }),
 }
 );
 const res3 = await fetch(workflowWebhookUrl(token3), {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: JSON.stringify({ message: 'three' }),
 });
 expect(res3.status).toBe(200);
 const body3 = await res3.text();
 expect(body3).toBe('Hello from webhook!');

 const returnValue = await run.returnValue;
 expect(returnValue).toHaveLength(3);
 expect(returnValue[0].url).toBe(
 new URL(
 `/.well-known/workflow/v1/webhook/${encodeURIComponent(token)}`,
 deploymentUrl
 ).href
 );
 expect(returnValue[0].url).toBe(workflowWebhookUrl(token));
 expect(returnValue[0].method).toBe('POST');
 expect(returnValue[0].body).toBe('{"message":"one"}');

 expect(returnValue[1].url).toBe(
 new URL(
 `/.well-known/workflow/v1/webhook/${encodeURIComponent(token2)}`,
 deploymentUrl
 ).href
 );
 expect(returnValue[1].url).toBe(workflowWebhookUrl(token2));
 expect(returnValue[1].method).toBe('POST');
 expect(returnValue[1].body).toBe('{"message":"two"}');

 expect(returnValue[2].url).toBe(
 new URL(
 `/.well-known/workflow/v1/webhook/${encodeURIComponent(token3)}`,
 deploymentUrl
 ).href
 );
 expect(returnValue[2].url).toBe(workflowWebhookUrl(token3));
 expect(returnValue[2].method).toBe('POST');
 expect(returnValue[2].body).toBe('{"message":"three"}');
 });
Expand DownExpand Up@@ -730,17 +695,11 @@ describe('e2e', () => {
 continue;
 }

 const res = await fetch(
 new URL(
 `/.well-known/workflow/v1/webhook/${encodeURIComponent(unservedHook.token)}`,
 deploymentUrl
 ),
 {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: `body-${unservedHook.token}`,
 }
 );
 const res = await fetch(workflowWebhookUrl(unservedHook.token), {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: `body-${unservedHook.token}`,
 });
 expect(res.status).toBe(202);
 servedTokens.add(unservedHook.token);
 }
Expand DownExpand Up@@ -786,11 +745,7 @@ describe('e2e', () => {
 );

 test('webhook route with invalid token', { timeout: 60_000 }, async () => {
 const invalidWebhookUrl = new URL(
 `/.well-known/workflow/v1/webhook/${encodeURIComponent('invalid')}`,
 deploymentUrl
 );
 const res = await fetch(invalidWebhookUrl, {
 const res = await fetch(workflowWebhookUrl('invalid'), {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: JSON.stringify({}),
Expand DownExpand Up@@ -2555,14 +2510,13 @@ describe('e2e', () => {
 // bypasses protection by sending messages through the Queue infrastructure.

 // Test the flow endpoint health check (V2: combined handler for both workflow + step)
 const flowHealthUrl = new URL(
 '/.well-known/workflow/v1/flow?__health',
 deploymentUrl
 const flowRes = await fetch(
 createWorkflowUrl(deploymentUrl, { type: 'health' }),
 {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 }
 );
 const flowRes = await fetch(flowHealthUrl, {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 });
 expect(flowRes.status).toBe(200);
 expect(flowRes.headers.get('Content-Type')).toBe('application/json');
 const flowBody = await flowRes.json();
Expand Down

3 changes: 2 additions & 1 deletion
packages/core/e2e/utils.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -3,6 +3,7 @@ import fs from 'node:fs';
import path, { dirname } from 'node:path';
import { setTimeout as sleep } from 'node:timers/promises';
import { fileURLToPath } from 'node:url';
import { createWorkflowUrl } from '@workflow/utils';
import { createVercelWorld } from '@workflow/world-vercel';
import { onTestFailed } from 'vitest';
import { getTrustedSourcesHeaders } from '../../../scripts/trusted-sources-headers.mjs';
Expand DownExpand Up@@ -373,7 +374,7 @@ export async function fetchManifest(
 const forceRefresh = options?.forceRefresh ?? false;
 if (cachedManifest && !forceRefresh) return cachedManifest;

 const url = new URL('/.well-known/workflow/v1/manifest.json', deploymentUrl);
 const url = createWorkflowUrl(deploymentUrl, { type: 'manifest' });
 const res = await fetch(url, {
 headers: await getTrustedSourcesHeaders(),
 });
Expand Down

4 changes: 2 additions & 2 deletions
packages/core/src/create-hook.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -167,8 +167,8 @@ export interface HookOptions {
 * Whether this hook can be resumed via the public webhook endpoint.
 *
 * When `true`, the hook can be triggered by sending an HTTP request to the
 * public `/.well-known/workflow/v1/webhook/{token}` URL. This is automatically
 * set when using `createWebhook()`.
 * public workflowwebhook URL. This is automatically set when using
 * `createWebhook()`.
 *
 * When `false` (the default), the hook can only be resumed server-side
 * via `resumeHook()`.
Expand Down

9 changes: 8 additions & 1 deletion
packages/core/src/runtime.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -9,6 +9,7 @@ import {
 RunExpiredError,
 WorkflowRuntimeError,
} from '@workflow/errors';
import { setWorkflowBasePath } from '@workflow/utils';
import {
 parseWorkflowName,
 workflowDisplayName,
Expand DownExpand Up@@ -293,8 +294,14 @@ function hasOpenHookOrWait(events: Event[]): boolean {
 */
export function workflowEntrypoint(
 workflowCode: string,
 options?: { namespace?: string; routeModuleBodyStartedAt?: number }
 options?: {
 namespace?: string;
 routeModuleBodyStartedAt?: number;
 basePath?: string;
 }
): (req: Request) => Promise<Response> {
 setWorkflowBasePath(options?.basePath);

 const NO_INLINE_REPLAY_AFTER_MS =
 Number(process.env.WORKFLOW_V2_TIMEOUT_MS) || 120_000;

Expand Down
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
// Universal Dark Mode - works on any site
(function() {
var enabled = true;
function applyDarkMode() {
if (!enabled) return;
// Create style element if it doesn't exist
var style = document.getElementById('universal-dark-mode-style');
if (!style) {
style = document.createElement('style');
style.id = 'universal-dark-mode-style';
document.head.appendChild(style);
}
// Dark mode CSS - inverts colors but preserves images/video
style.textContent = '
/* Invert everything except media */
html {
filter: invert(1) hue-rotate(180deg) !important;
background: #1a1a2e !important;
}
/* Restore images, videos, iframes, canvas */
img, video, iframe, canvas, svg, picture, [style*="background-image"] {
filter: invert(1) hue-rotate(180deg) !important;
}
/* Preserve specific elements that should not be inverted */
.no-dark-mode, .no-dark-mode *,
[data-theme="light"], [data-theme="light"],
.ace_editor, .ace_editor *,
.CodeMirror, .CodeMirror *,
.monaco-editor, .monaco-editor *,
.markdown-body pre, .markdown-body pre *,
.highlight, .highlight *,
pre code, pre code * {
filter: none !important;
}
/* Fix common UI elements */
.modal, .popup, .dropdown-menu, .tooltip, .popover {
filter: invert(1) hue-rotate(180deg) !important;
background: #2d2d44 !important;
border-color: #444 !important;
}
/* Scrollbars */
::-webkit-scrollbar { background: #1a1a2e !important; }
::-webkit-scrollbar-thumb { background: #444 !important; }
::-webkit-scrollbar-thumb:hover { background: #555 !important; }
/* Selection */
::selection { background: #4ecdc4 !important; color: #1a1a2e !important; }
::-moz-selection { background: #4ecdc4 !important; color: #1a1a2e !important; }
';
}
function removeDarkMode() {
var style = document.getElementById('universal-dark-mode-style');
if (style) style.remove();
}
// Toggle with Alt+Shift+D
document.addEventListener('keydown', function(e) {
if (e.altKey && e.shiftKey && e.key === 'D') {
e.preventDefault();
enabled = !enabled;
if (enabled) {
applyDarkMode();
console.log('[Universal Dark Mode] Enabled');
} else {
removeDarkMode();
console.log('[Universal Dark Mode] Disabled');
}
}
});
// Apply on load
applyDarkMode();
// Re-apply on dynamic content
var observer = new MutationObserver(function(mutations) {
if (enabled && !document.getElementById('universal-dark-mode-style')) {
applyDarkMode();
}
});
observer.observe(document.head, { childList: true });
console.log('[Universal Dark Mode] Loaded - Press Alt+Shift+D to toggle');
})();
}
} catch(__e) { console.warn('[Userscript:Universal Dark Mode]', __e); }
})();
})();
fix(next): respect basePath for workflow routes by NathanColosimo · Pull Request #2732 · vercel/workflow · GitHub
Skip to content
fix(next): respect basePath for workflow routes#2732

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

NathanColosimo
merged 9 commits into

from

Jul 6, 2026
 Merged


fix(next): respect basePath for workflow routes
#2732
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


9 commits


Select commit
Hold shift + click to select a range
7b44046

fix(next): respect basePath for workflow routes


NathanColosimo Jul 2, 2026
d06c57f

docs(core): note workflow URL resolution gap


NathanColosimo Jul 2, 2026
610c9c0

fix(next): expose workflow health route methods


NathanColosimo Jul 2, 2026
18a9a2d

test(utils): remove workflow route helper tests


NathanColosimo Jul 2, 2026
0017fca

test(builders): remove route handler string test


NathanColosimo Jul 2, 2026
cbbd394

fix(next): defer basePath validation to Next.js


NathanColosimo Jul 2, 2026
e157fba

refactor(utils): remove workflow url helper wrappers


NathanColosimo Jul 2, 2026
4fb7f19

Test Next basePath builder wiring


NathanColosimo Jul 6, 2026
ce1ddb2

Merge remote-tracking branch 'origin/main' into nathanc/fix-next-base…


NathanColosimo Jul 6, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


10 changes: 10 additions & 0 deletions
.changeset/next-base-path.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
---
"@workflow/builders": patch
"@workflow/core": patch
"@workflow/next": patch
"@workflow/utils": patch
"@workflow/world-local": patch
"@workflow/world-postgres": patch
---

Respect framework base paths when routing workflow traffic and expose health checks on generated Next.js workflow routes.

14 changes: 10 additions & 4 deletions
packages/builders/src/base-builder.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -23,7 +23,10 @@ import {
 applySwcTransform,
 type WorkflowManifest,
} from './apply-swc-transform.js';
import { createWorkflowEntrypointOptionsCode } from './constants.js';
import {
 createWorkflowEntrypointOptionsCode,
 createWorkflowRouteHandlersCode,
} from './constants.js';
import { getEsbuildTsconfigOptions } from './esbuild-tsconfig.js';
import {
 type DiscoveredEntries,
Expand DownExpand Up@@ -1564,6 +1567,7 @@ export const __steps_registered = true;

 const workflowEntrypointOptionsCode = createWorkflowEntrypointOptionsCode(
 {
 basePath: this.config.basePath,
 routeModuleBodyStartedAt: 'workflowRouteModuleBodyStartedAt',
 }
 );
Expand All@@ -1578,7 +1582,7 @@ import { workflowEntrypoint } from 'workflow/runtime';
const workflowRouteModuleBodyStartedAt = Date.now();
const workflowCode = \`${workflowBundleCode.replace(/[\\`$]/g, '\\$&')}\`;

export const POST = workflowEntrypoint(workflowCode${workflowEntrypointOptionsCode});`;
${createWorkflowRouteHandlersCode(`workflowEntrypoint(workflowCode${workflowEntrypointOptionsCode})`)}`;

 // we skip the final bundling step for Next.js so it can bundle itself
 if (!bundleFinalOutput) {
Expand DownExpand Up@@ -1771,6 +1775,7 @@ export const POST = workflowEntrypoint(workflowCode${workflowEntrypointOptionsCo
 const stepsRelativePath = `./${basename(stepsOutfile).replace(/\\/g, '/')}`;
 const escapedVMCode = workflowVMCode.replace(/[\\`$]/g, '\\$&');
 const workflowEntrypointOptionsCode = createWorkflowEntrypointOptionsCode({
 basePath: this.config.basePath,
 routeModuleBodyStartedAt: 'workflowRouteModuleBodyStartedAt',
 });

Expand All@@ -1786,7 +1791,7 @@ void __steps_registered;

const workflowCode = \`${escapedVMCode}\`;

export const POST = workflowEntrypoint(workflowCode${workflowEntrypointOptionsCode});`;
${createWorkflowRouteHandlersCode(`workflowEntrypoint(workflowCode${workflowEntrypointOptionsCode})`)}`;

 if (!bundleFinalOutput) {
 await this.writeGeneratedFile(flowOutfile, combinedFunctionCode);
Expand DownExpand Up@@ -1849,6 +1854,7 @@ export const POST = workflowEntrypoint(workflowCode${workflowEntrypointOptionsCo
 const escaped = interimBundleText.replace(/[\\`$]/g, '\\$&');
 const workflowEntrypointOptionsCode = createWorkflowEntrypointOptionsCode(
 {
 basePath: this.config.basePath,
 routeModuleBodyStartedAt: 'workflowRouteModuleBodyStartedAt',
 }
 );
Expand All@@ -1864,7 +1870,7 @@ void __steps_registered;

const workflowCode = \`${escaped}\`;

export const POST = workflowEntrypoint(workflowCode${workflowEntrypointOptionsCode});`;
${createWorkflowRouteHandlersCode(`workflowEntrypoint(workflowCode${workflowEntrypointOptionsCode})`)}`;

 const outputDir = dirname(flowOutfile);
 await mkdir(outputDir, { recursive: true });
Expand Down

3 changes: 2 additions & 1 deletion
packages/builders/src/constants.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -53,10 +53,11 @@ describe('createWorkflowEntrypointOptionsCode', () => {
 expect(
 createWorkflowEntrypointOptionsCode({
 namespace: 'custom',
 basePath: '/v2',
 routeModuleBodyStartedAt: 'workflowRouteModuleBodyStartedAt',
 })
 ).toBe(
 ', { namespace: "custom", routeModuleBodyStartedAt: workflowRouteModuleBodyStartedAt }'
 ', { namespace: "custom", basePath: "/v2", routeModuleBodyStartedAt: workflowRouteModuleBodyStartedAt }'
 );
 });
});

14 changes: 14 additions & 0 deletions
packages/builders/src/constants.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -54,6 +54,7 @@ export function createWorkflowQueueTrigger(options?: { namespace?: string }) {
 */
export function createWorkflowEntrypointOptionsCode(options?: {
 namespace?: string;
 basePath?: string;
 /** Raw code identifier/expression emitted into generated route files, not data. */
 routeModuleBodyStartedAt?: string;
}) {
Expand All@@ -66,6 +67,10 @@ export function createWorkflowEntrypointOptionsCode(options?: {
 fields.push(`namespace: ${JSON.stringify(namespace)}`);
 }

 if (options?.basePath !== undefined) {
 fields.push(`basePath: ${JSON.stringify(options.basePath)}`);
 }

 if (options?.routeModuleBodyStartedAt) {
 fields.push(
 `routeModuleBodyStartedAt: ${options.routeModuleBodyStartedAt}`
Expand All@@ -79,6 +84,15 @@ export function createWorkflowEntrypointOptionsCode(options?: {
 return `, { ${fields.join(', ')} }`;
}

export function createWorkflowRouteHandlersCode(
 workflowEntrypointCall: string
) {
 return `export const POST = ${workflowEntrypointCall};
export const GET = POST;
export const HEAD = POST;
export const OPTIONS = POST;`;
}

/**
 * Default queue trigger (no namespace). Backward compatible.
 */
Expand Down

3 changes: 3 additions & 0 deletions
packages/builders/src/types.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -60,6 +60,9 @@ interface BaseWorkflowConfig {
 // artifact locations.
 distDir?: string;

 // Optional route prefix for apps deployed below the origin root.
 basePath?: string;

 // Suppress informational logs emitted by createWorkflowsBundle()
 // (e.g. intermediate/final workflow bundle timing logs).
 suppressCreateWorkflowsBundleLogs?: boolean;
Expand Down

124 changes: 39 additions & 85 deletions
packages/core/e2e/e2e.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -10,6 +10,7 @@ import {
 WorkflowRunFailedError,
 WorkflowWorldError,
} from '@workflow/errors';
import { createWorkflowUrl } from '@workflow/utils';
import { SPEC_VERSION_CURRENT, type World } from '@workflow/world';
import {
 afterAll,
Expand DownExpand Up@@ -111,6 +112,9 @@ function writeE2EMetadata() {
const e2e = (fn: string) =>
 getWorkflowMetadata(deploymentUrl, 'workflows/99_e2e.ts', fn);

const workflowWebhookUrl = (token: string) =>
 createWorkflowUrl(deploymentUrl, { type: 'webhook', token });

type WorkflowEvent = Awaited<
 ReturnType<World['events']['list']>
>['data'][number];
Expand DownExpand Up@@ -532,17 +536,11 @@ describe('e2e', () => {
 expect(hook.runId).toBe(run.runId);

 // Attempt to resume via the public webhook endpoint — should get 404
 const res = await fetch(
 new URL(
 `/.well-known/workflow/v1/webhook/${encodeURIComponent(token)}`,
 deploymentUrl
 ),
 {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: JSON.stringify({ message: 'should-be-rejected' }),
 }
 );
 const res = await fetch(workflowWebhookUrl(token), {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: JSON.stringify({ message: 'should-be-rejected' }),
 });
 expect(res.status).toBe(404);

 // Now resume via server-side resumeHook() — should work
Expand DownExpand Up@@ -587,79 +585,46 @@ describe('e2e', () => {
 const [token, token2, token3] = hooks.map((h) => h.token);

 // Webhook with default response
 const res = await fetch(
 new URL(
 `/.well-known/workflow/v1/webhook/${encodeURIComponent(token)}`,
 deploymentUrl
 ),
 {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: JSON.stringify({ message: 'one' }),
 }
 );
 const res = await fetch(workflowWebhookUrl(token), {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: JSON.stringify({ message: 'one' }),
 });
 expect(res.status).toBe(202);
 const body = await res.text();
 expect(body).toBe('');

 // Webhook with static response
 const res2 = await fetch(
 new URL(
 `/.well-known/workflow/v1/webhook/${encodeURIComponent(token2)}`,
 deploymentUrl
 ),
 {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: JSON.stringify({ message: 'two' }),
 }
 );
 const res2 = await fetch(workflowWebhookUrl(token2), {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: JSON.stringify({ message: 'two' }),
 });
 expect(res2.status).toBe(402);
 const body2 = await res2.text();
 expect(body2).toBe('Hello from static response!');

 // Webhook with manual response
 const res3 = await fetch(
 new URL(
 `/.well-known/workflow/v1/webhook/${encodeURIComponent(token3)}`,
 deploymentUrl
 ),
 {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: JSON.stringify({ message: 'three' }),
 }
 );
 const res3 = await fetch(workflowWebhookUrl(token3), {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: JSON.stringify({ message: 'three' }),
 });
 expect(res3.status).toBe(200);
 const body3 = await res3.text();
 expect(body3).toBe('Hello from webhook!');

 const returnValue = await run.returnValue;
 expect(returnValue).toHaveLength(3);
 expect(returnValue[0].url).toBe(
 new URL(
 `/.well-known/workflow/v1/webhook/${encodeURIComponent(token)}`,
 deploymentUrl
 ).href
 );
 expect(returnValue[0].url).toBe(workflowWebhookUrl(token));
 expect(returnValue[0].method).toBe('POST');
 expect(returnValue[0].body).toBe('{"message":"one"}');

 expect(returnValue[1].url).toBe(
 new URL(
 `/.well-known/workflow/v1/webhook/${encodeURIComponent(token2)}`,
 deploymentUrl
 ).href
 );
 expect(returnValue[1].url).toBe(workflowWebhookUrl(token2));
 expect(returnValue[1].method).toBe('POST');
 expect(returnValue[1].body).toBe('{"message":"two"}');

 expect(returnValue[2].url).toBe(
 new URL(
 `/.well-known/workflow/v1/webhook/${encodeURIComponent(token3)}`,
 deploymentUrl
 ).href
 );
 expect(returnValue[2].url).toBe(workflowWebhookUrl(token3));
 expect(returnValue[2].method).toBe('POST');
 expect(returnValue[2].body).toBe('{"message":"three"}');
 });
Expand DownExpand Up@@ -730,17 +695,11 @@ describe('e2e', () => {
 continue;
 }

 const res = await fetch(
 new URL(
 `/.well-known/workflow/v1/webhook/${encodeURIComponent(unservedHook.token)}`,
 deploymentUrl
 ),
 {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: `body-${unservedHook.token}`,
 }
 );
 const res = await fetch(workflowWebhookUrl(unservedHook.token), {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: `body-${unservedHook.token}`,
 });
 expect(res.status).toBe(202);
 servedTokens.add(unservedHook.token);
 }
Expand DownExpand Up@@ -786,11 +745,7 @@ describe('e2e', () => {
 );

 test('webhook route with invalid token', { timeout: 60_000 }, async () => {
 const invalidWebhookUrl = new URL(
 `/.well-known/workflow/v1/webhook/${encodeURIComponent('invalid')}`,
 deploymentUrl
 );
 const res = await fetch(invalidWebhookUrl, {
 const res = await fetch(workflowWebhookUrl('invalid'), {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 body: JSON.stringify({}),
Expand DownExpand Up@@ -2555,14 +2510,13 @@ describe('e2e', () => {
 // bypasses protection by sending messages through the Queue infrastructure.

 // Test the flow endpoint health check (V2: combined handler for both workflow + step)
 const flowHealthUrl = new URL(
 '/.well-known/workflow/v1/flow?__health',
 deploymentUrl
 const flowRes = await fetch(
 createWorkflowUrl(deploymentUrl, { type: 'health' }),
 {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 }
 );
 const flowRes = await fetch(flowHealthUrl, {
 method: 'POST',
 headers: await getTrustedSourcesHeaders(),
 });
 expect(flowRes.status).toBe(200);
 expect(flowRes.headers.get('Content-Type')).toBe('application/json');
 const flowBody = await flowRes.json();
Expand Down

3 changes: 2 additions & 1 deletion
packages/core/e2e/utils.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -3,6 +3,7 @@ import fs from 'node:fs';
import path, { dirname } from 'node:path';
import { setTimeout as sleep } from 'node:timers/promises';
import { fileURLToPath } from 'node:url';
import { createWorkflowUrl } from '@workflow/utils';
import { createVercelWorld } from '@workflow/world-vercel';
import { onTestFailed } from 'vitest';
import { getTrustedSourcesHeaders } from '../../../scripts/trusted-sources-headers.mjs';
Expand DownExpand Up@@ -373,7 +374,7 @@ export async function fetchManifest(
 const forceRefresh = options?.forceRefresh ?? false;
 if (cachedManifest && !forceRefresh) return cachedManifest;

 const url = new URL('/.well-known/workflow/v1/manifest.json', deploymentUrl);
 const url = createWorkflowUrl(deploymentUrl, { type: 'manifest' });
 const res = await fetch(url, {
 headers: await getTrustedSourcesHeaders(),
 });
Expand Down

4 changes: 2 additions & 2 deletions
packages/core/src/create-hook.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -167,8 +167,8 @@ export interface HookOptions {
 * Whether this hook can be resumed via the public webhook endpoint.
 *
 * When `true`, the hook can be triggered by sending an HTTP request to the
 * public `/.well-known/workflow/v1/webhook/{token}` URL. This is automatically
 * set when using `createWebhook()`.
 * public workflowwebhook URL. This is automatically set when using
 * `createWebhook()`.
 *
 * When `false` (the default), the hook can only be resumed server-side
 * via `resumeHook()`.
Expand Down

9 changes: 8 additions & 1 deletion
packages/core/src/runtime.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -9,6 +9,7 @@ import {
 RunExpiredError,
 WorkflowRuntimeError,
} from '@workflow/errors';
import { setWorkflowBasePath } from '@workflow/utils';
import {
 parseWorkflowName,
 workflowDisplayName,
Expand DownExpand Up@@ -293,8 +294,14 @@ function hasOpenHookOrWait(events: Event[]): boolean {
 */
export function workflowEntrypoint(
 workflowCode: string,
 options?: { namespace?: string; routeModuleBodyStartedAt?: number }
 options?: {
 namespace?: string;
 routeModuleBodyStartedAt?: number;
 basePath?: string;
 }
): (req: Request) => Promise<Response> {
 setWorkflowBasePath(options?.basePath);

 const NO_INLINE_REPLAY_AFTER_MS =
 Number(process.env.WORKFLOW_V2_TIMEOUT_MS) || 120_000;

Expand Down
Loading
Loading