You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
fix(utils,auth,protocol): a browser Web Worker gets the browser variants; Node variants go to workerd - #1038
webpack's target: 'webworker' resolves packages with the worker and browser conditions. @frontmcp/utils mapped worker to its Node variants, both in its imports (#crypto-provider, #async-context, #event-emitter, #env, #runtime-context, #path) and, since #1030, in its root export, where it selects the single-file ESM bundle. @frontmcp/auth's root export did the same, and so did @frontmcp/protocol's #mcp-streamable-http, #mcp-server and #server-types (which imports http). So a browser Web Worker got node:crypto, AsyncLocalStorage, node:events, node:path and process.env. On the base, webpack's target: 'webworker' build of create() + one tool stops on 13 unresolved Node built-ins. With those left empty, the worker throws while it loads.
What each runtime passes
I checked each runtime in its bundler's source and built with it where I could.
Bundler or runtime
Conditions it adds
Before
After
webpack 5.105, target: 'webworker'
worker, browser
Node variants
browser variants
webpack, worker entry (new Worker(new URL(...))) in a target: 'web' build
worker only for the entry request. The worker's imports resolve like the page's.
browser
browser
Parcel (@parcel/node-resolver-core 3.7), web and service workers
wrangler 4.100 (and every release since 2.9, so all of 3.x), including Pages Functions
workerd, worker, browser
Node
Node (same files)
@cloudflare/vite-plugin 1.67
workerd, worker, module, browser
Node
Node
@cloudflare/vitest-pool-workers 0.23
workerd, worker, module, browser
Node
Node
OpenNext for Cloudflare 1.20
workerd (esbuild, platform: 'node')
Node
Node
Vercel Edge: Next.js 16.4 (webpack and Turbopack), @vercel/node 29
edge-light, browser
browser
browser
Netlify Edge (@netlify/edge-bundler 16.2)
node (esbuild, platform: 'node')
Node
Node
Fastly Compute (@fastly/js-compute 4.0)
fastly, browser
browser
browser
Deno, Bun, Node, AWS Lambda
deno / bun / node
Node
Node
webpack, wrangler, Vite and esbuild were built with from the repo's node_modules. Rollup was built with from a scratch install. For Parcel, Next.js, Turbopack, @vercel/node, Netlify, Fastly, OpenNext, @cloudflare/vite-plugin, @cloudflare/vitest-pool-workers and wrangler 2.x and 3.0, I read the published source. Miniflare runs what it is given and doesn't bundle.
No frontmcp build target passes worker. --target cloudflare leaves bundling to wrangler; vercel and lambda bundle with rspack target: 'node'; browser uses esbuild with browser; the SEA and mcpb builds use esbuild platform: 'node'.
Two notes in the issue don't hold for these versions:
Vercel Edge passes edge-light and browser, not worker. It got the browser variants before this change and still does.
In a target: 'web' build, webpack's worker entry applies worker to the entry request only. Its imports resolve like the page's, so only target: 'webworker' (and Parcel) hit the bug.
Rollup without browser: true builds for Node, so the worker key never reached it. There's nothing to fix in the packages for that case: the catalog now tells Rollup users to pass browser: true.
What changes
The Node variants are keyed on workerd, the condition only Cloudflare's bundlers pass, instead of worker:
@frontmcp/utils: the six imports and the root export.
@frontmcp/auth: the root export.
@frontmcp/protocol: #mcp-streamable-http, #mcp-server and #server-types.
The worker keys that already point at the browser stubs or at the shared file stay, because they're right for any worker: protocol's #stdio-client, #stdio-server and #client, and the SDK's #sse-transport, #express-host and #protocol-client. The SDK's root export has no worker key. A browser Web Worker now resolves every split the way a page does.
Cloudflare keeps exactly the files it resolved before. I ran wrangler deploy --dry-run --metafile (wrangler 4.100) on a Worker serving createFetchHandler + one tool, built from the packages before and after the change. Both runs bundle the same 1,652 inputs into a byte-identical worker.js (SHA-1 99ff8beaf8365db6921abc7bf82f26ba4d0b2461). The same dry run on the frontmcp build --target cloudflare output of demo-e2e-cloudflare's fixture also bundles the same 2,424 inputs into a byte-identical index.js. nx test demo-e2e-cloudflare, which runs frontmcp build --target cloudflare and then wrangler dev on workerd, passes.
A Worker bundled by hand with worker and browser but without workerd now gets the browser variants. Those variants read no environment variables and have no Web-standard MCP transport. The skipped managed-edge-autoupdate e2e bundled that way, and it now passes wrangler's three conditions. The Cloudflare reference tells custom bundlers to pass workerd.
Not in this PR
On the base and on this branch, a webpack 5 build of the SDK for a page (target: 'web') stops on 6 node: URIs that webpack can't read without configuration:
node:cluster, node:net and node:path from server/security/unix-socket-guard;
node:http and node:stream from shared/unix-socket-fetch;
node:os from shared/shared-files.
The first three come from a static chain, index → provider/create-container → duty/duty.lifecycle (#1014) → server/security/unix-socket-guard. The other three come through the import('../shared/index.js') in FrontMcpInstance.runShared (#1019), which webpack follows too. The per-module browser build keeps these node: imports. Vite replaces them with an empty module and the bundle-size e2e marks them external, but webpack 5 refuses the node: scheme. That build failure isn't specific to Web Workers. After this change a target: 'webworker' build fails on the same 6 URIs, down from 13. The e2e's webpack build leaves Node built-ins empty, as a webpack app has to today. This deserves its own issue.
Bundle size
nx run-many -t build -p utils auth protocol sdk plugin-webmcp --skip-nx-cache, then nx test demo-e2e-bundle-size:
A page resolves browser, which this change doesn't touch, so the page bundles don't move.
User-facing change
What changed:@frontmcp/utils, @frontmcp/auth and @frontmcp/protocol give their Node variants to the workerd condition instead of worker. A browser Web Worker now gets the browser variants, as a page does. This covers webpack's target: 'webworker', Parcel's workers, and esbuild or Rollup given worker alongside browser. Cloudflare Workers built by wrangler or @cloudflare/vite-plugin resolve the same files as before.
Before → after:
Under webpack target: 'webworker', create() failed with process is not defined or an unresolved Node built-in. It now starts and serves tools.
A Worker bundled by hand with worker + browser and no workerd used to get the Node variants and now gets the browser ones. It has to pass workerd, as wrangler does.
frontmcp.dev pages affected (if known): the browser deployment page (Web Workers), the Cloudflare Workers deployment page (custom bundlers and the workerd condition).
Skills catalog entries updated:
frontmcp-deployment/references/build-for-browser.md: Web Workers get the browser builds, Rollup needs browser: true, esbuild needs platform: 'browser', plus a troubleshooting row.
frontmcp-deployment/references/deploy-to-cloudflare.md: wrangler's conditions, custom bundlers must pass workerd, plus a troubleshooting row.
Tests
apps/e2e/demo-e2e-bundle-size/e2e/browser-web-worker.e2e.spec.ts (new). It bundles create() + one tool as a browser Web Worker twice: with webpack target: 'webworker', and with esbuild platform: 'browser' + conditions: ['worker']. Each bundle is checked for the Node variants of utils, auth and protocol, then run in a worker-like context with no process, Buffer, global or setImmediate, where the worker posts its tool result.
On the base, the webpack bundle holds 11 Node variants and throws at load. The esbuild bundle throws AsyncLocalStorage is not a constructor.
With the fix, both pass.
The helper's Node built-in stub now matches names with digits, such as node:http2.
scripts/worker-export-conditions.test.mjs. For every imports and exports entry of every package under libs/ and plugins/, it checks that a browser Web Worker resolves the file a page resolves, for import and require, with and without module. It also resolves every split and the utils and auth root exports with the condition sets of Cloudflare (workerd, worker, browser), a browser Web Worker (worker, browser), Vercel Edge (edge-light, browser), a browser and Node.
Cloudflare keeps the Node variants and the ESM bundle. Every other set gets what a browser or Node got before.
On the base, 5 of 9 failed (every browser Web Worker case). Now 9 pass.
scripts/strip-dist-from-pkg.test.mjs. Its subpath-import fixture maps the Node variant with workerd, as the packages now do.
Results:
nx test demo-e2e-bundle-size: 10 suites, 44 tests passed, with the sizes above.
nx test demo-e2e-cloudflare: 2 suites, 16 tests passed. One suite is skipped as on the base.
tsc --noEmit -p apps/e2e/demo-e2e-bundle-size/tsconfig.e2e.json: no errors.
Prettier clean.
By hand: the wrangler dry run above, webpack target: 'web' with and without a worker entry, and Rollup with browser: true, without it, and with browser: true + exportConditions: ['worker'], each before and after the change.
Summary by CodeRabbit
Bug Fixes
Improved package resolution for browser Web Workers and Cloudflare Workers, helping each environment use compatible builds.
Added coverage for bundling and running Web Worker builds with webpack and esbuild.
Documentation
Updated browser-build and Cloudflare deployment guidance with resolver settings and troubleshooting for custom bundles.
webpack's target: 'webworker', Parcel's workers, and esbuild or Rollup
given the `worker` condition resolve `worker` and `browser`. @frontmcp/utils
mapped `worker` to its Node variants in its imports (#crypto-provider,
#async-context, #event-emitter, #env, #runtime-context, #path) and its root
export, @frontmcp/auth in its root export, and @frontmcp/protocol in
#mcp-streamable-http, #mcp-server and #server-types, so the SDK failed in a
browser Web Worker with `process is not defined` or a missing Node built-in.
The Node variants now take the `workerd` condition, which wrangler and
@cloudflare/vite-plugin pass with `worker` and `browser`, so a Cloudflare
Worker resolves the same files as before (a wrangler dry run bundles the
same 1,652 inputs into a byte-identical worker.js) and a browser Web Worker
gets the browser variants, as a page does. The `worker` keys that already
pointed at stubs stay.
Fixes#1031
…e files it gives a page
The guard listed the splits by hand, so it missed the SDK's #protocol-client and would not catch a new split
that maps `worker` to a Node file. It now resolves every imports and exports entry of every workspace package
with and without `worker`, for import and require.
No actionable comments were generated in the recent review.
Walkthrough
Package export conditions now use workerd for Node variants, while browser Web Workers resolve browser variants. The changes update Cloudflare resolution checks and deployment guidance, and add webpack and esbuild end-to-end coverage for bundling and running a Web Worker fixture.
Changes: Worker Runtime Conditions and Browser Coverage
Layer / File(s)
Summary
Separate Workerd and browser conditions libs/auth/package.json, libs/protocol/package.json, libs/utils/package.json, apps/e2e/demo-e2e-cloudflare/e2e/managed-edge-autoupdate.e2e.spec.ts, scripts/strip-dist-from-pkg.js, scripts/strip-dist-from-pkg.test.mjs, libs/skills/catalog/frontmcp-deployment/references/build-for-browser.md, libs/skills/catalog/frontmcp-deployment/references/deploy-to-cloudflare.md
Package mappings use workerd for Node variants. The Cloudflare test configuration, package-rewrite test, and deployment guidance reflect the updated condition.
The tests check expected implementations across Cloudflare, browser Web Workers, Vercel Edge, browsers, and Node. They also compare workspace package resolution between browser Web Workers and pages.
Bundle and run the Web Worker fixture apps/e2e/demo-e2e-bundle-size/e2e/browser-web-worker.e2e.spec.ts, apps/e2e/demo-e2e-bundle-size/e2e/helpers/browser-bundle.ts, apps/e2e/demo-e2e-bundle-size/e2e/helpers/run-in-web-worker.mjs, apps/e2e/demo-e2e-bundle-size/fixture/web-worker-create-tool.mjs
Webpack and esbuild bundle the fixture for a Web Worker. The test checks bundle inputs and runs the bundle to verify the tool result.
Browser workers receive browser mappings while Cloudflare retains its existing mappings. No merge-blocking risk was established.
Pre-merge checks: 5
Check name
Status
Explanation
Title check
The title names the three packages (utils, auth, protocol) and states the main behavior change: a browser Web Worker gets browser variants, and Node variants move to the workerd condition. The changes…
Description check
The description follows the repository template. It includes 'What and why' with the bug, the issue link (#1031), and the cause. It includes a 'User-facing change' section with what changed, before/af…
Linked Issues check
Issue #1031 requires browser Web Workers to resolve browser variants and Cloudflare Workers to retain their current variants. The package maps in @frontmcp/utils, @frontmcp/auth, and `@frontmcp/pr…
Out of Scope Changes check
The changes remain within issue #1031. Package-map updates implement the condition fix. The export-condition tests, Web Worker end-to-end fixture, bundler helpers, Cloudflare condition update, documen…
Docstring Coverage
Docstring coverage is 66.67% which is sufficient. The required threshold is 65.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentati…
Full details: Title check
Explanation
The title names the three packages (utils, auth, protocol) and states the main behavior change: a browser Web Worker gets browser variants, and Node variants move to the workerd condition. The changeset matches this. The title is long (101 characters) and uses a semicolon-joined clause, but it is specific and on-topic.
Full details: Description check
Explanation
The description follows the repository template. It includes 'What and why' with the bug, the issue link (#1031), and the cause. It includes a 'User-facing change' section with what changed, before/after, affected frontmcp.dev pages, and skills catalog entries. It includes a detailed 'Tests' section with the tests run and manual checks. The template's placeholder comments are gone, and the content fills each required section.
Full details: Linked Issues check
Explanation
Issue #1031 requires browser Web Workers to resolve browser variants and Cloudflare Workers to retain their current variants. The package maps in @frontmcp/utils, @frontmcp/auth, and @frontmcp/protocol move only the Node mappings from worker to workerd. The new condition tests check browser-worker, browser, Node, Vercel Edge, and Cloudflare resolution. The new webpack and esbuild end-to-end test runs create() and a tool without Node globals. These changes satisfy the coding requirements for #1031.
Full details: Out of Scope Changes check
Explanation
The changes remain within issue #1031. Package-map updates implement the condition fix. The export-condition tests, Web Worker end-to-end fixture, bundler helpers, Cloudflare condition update, documentation, and strip-dist fixture update verify or document the same runtime behavior. No unrelated implementation change is demonstrated.
Full details: Docstring Coverage
Explanation
Docstring coverage is 66.67% which is sufficient. The required threshold is 65.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentation-only edits and deletions within surviving functions are included; unchanged diff context and fully deleted functions are excluded. Analyzed 3 functions across 8 files. (5 skipped: 5 unsupported.)
Finishing Touches
Generate docstrings
Commit to this branch
Create a new PR
Generate unit tests (beta)
Commit to this branch
Create a new PR
Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts
CodeRabbit Verify
Run CodeRabbit Verify to test the changes in this pull request.
Included review availability: This review used your included allowance. Your plan provides up to 5 included reviews per hour; 0 remain after this review.
Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.
Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Stacked on #1037
What and why
Bug fix. Fixes #1031.
webpack's
target: 'webworker'resolves packages with theworkerandbrowserconditions.@frontmcp/utilsmappedworkerto its Node variants, both in itsimports(#crypto-provider,#async-context,#event-emitter,#env,#runtime-context,#path) and, since #1030, in its root export, where it selects the single-file ESM bundle.@frontmcp/auth's root export did the same, and so did@frontmcp/protocol's#mcp-streamable-http,#mcp-serverand#server-types(which importshttp). So a browser Web Worker gotnode:crypto,AsyncLocalStorage,node:events,node:pathandprocess.env. On the base, webpack'starget: 'webworker'build ofcreate()+ one tool stops on 13 unresolved Node built-ins. With those left empty, the worker throws while it loads.What each runtime passes
I checked each runtime in its bundler's source and built with it where I could.
target: 'webworker'worker,browsernew Worker(new URL(...))) in atarget: 'web'buildworkeronly for the entry request. The worker's imports resolve like the page's.@parcel/node-resolver-core3.7), web and service workersworker,browserplatform: 'browser',conditions: ['worker']worker,browserbrowser: true,exportConditions: ['worker']worker,browserbrowser: truebrowserbrowser: truedefault,module,import)module,browserworkerd,worker,browser@cloudflare/vite-plugin1.67workerd,worker,module,browser@cloudflare/vitest-pool-workers0.23workerd,worker,module,browserworkerd(esbuild,platform: 'node')@vercel/node29edge-light,browser@netlify/edge-bundler16.2)node(esbuild,platform: 'node')@fastly/js-compute4.0)fastly,browserdeno/bun/nodewebpack, wrangler, Vite and esbuild were built with from the repo's
node_modules. Rollup was built with from a scratch install. For Parcel, Next.js, Turbopack,@vercel/node, Netlify, Fastly, OpenNext,@cloudflare/vite-plugin,@cloudflare/vitest-pool-workersand wrangler 2.x and 3.0, I read the published source. Miniflare runs what it is given and doesn't bundle.No
frontmcp buildtarget passesworker.--target cloudflareleaves bundling to wrangler;vercelandlambdabundle with rspacktarget: 'node';browseruses esbuild withbrowser; the SEA andmcpbbuilds use esbuildplatform: 'node'.Two notes in the issue don't hold for these versions:
edge-lightandbrowser, notworker. It got the browser variants before this change and still does.target: 'web'build, webpack's worker entry appliesworkerto the entry request only. Its imports resolve like the page's, so onlytarget: 'webworker'(and Parcel) hit the bug.Rollup without
browser: truebuilds for Node, so theworkerkey never reached it. There's nothing to fix in the packages for that case: the catalog now tells Rollup users to passbrowser: true.What changes
The Node variants are keyed on
workerd, the condition only Cloudflare's bundlers pass, instead ofworker:@frontmcp/utils: the siximportsand the root export.@frontmcp/auth: the root export.@frontmcp/protocol:#mcp-streamable-http,#mcp-serverand#server-types.The
workerkeys that already point at the browser stubs or at the shared file stay, because they're right for any worker: protocol's#stdio-client,#stdio-serverand#client, and the SDK's#sse-transport,#express-hostand#protocol-client. The SDK's root export has noworkerkey. A browser Web Worker now resolves every split the way a page does.Cloudflare keeps exactly the files it resolved before. I ran
wrangler deploy --dry-run --metafile(wrangler 4.100) on a Worker servingcreateFetchHandler+ one tool, built from the packages before and after the change. Both runs bundle the same 1,652 inputs into a byte-identicalworker.js(SHA-199ff8beaf8365db6921abc7bf82f26ba4d0b2461). The same dry run on thefrontmcp build --target cloudflareoutput of demo-e2e-cloudflare's fixture also bundles the same 2,424 inputs into a byte-identicalindex.js.nx test demo-e2e-cloudflare, which runsfrontmcp build --target cloudflareand thenwrangler devon workerd, passes.A Worker bundled by hand with
workerandbrowserbut withoutworkerdnow gets the browser variants. Those variants read no environment variables and have no Web-standard MCP transport. The skippedmanaged-edge-autoupdatee2e bundled that way, and it now passes wrangler's three conditions. The Cloudflare reference tells custom bundlers to passworkerd.Not in this PR
On the base and on this branch, a webpack 5 build of the SDK for a page (
target: 'web') stops on 6node:URIs that webpack can't read without configuration:node:cluster,node:netandnode:pathfromserver/security/unix-socket-guard;node:httpandnode:streamfromshared/unix-socket-fetch;node:osfromshared/shared-files.The first three come from a static chain,
index→provider/create-container→duty/duty.lifecycle(#1014) →server/security/unix-socket-guard. The other three come through theimport('../shared/index.js')inFrontMcpInstance.runShared(#1019), which webpack follows too. The per-module browser build keeps thesenode:imports. Vite replaces them with an empty module and the bundle-size e2e marks them external, but webpack 5 refuses thenode:scheme. That build failure isn't specific to Web Workers. After this change atarget: 'webworker'build fails on the same 6 URIs, down from 13. The e2e's webpack build leaves Node built-ins empty, as a webpack app has to today. This deserves its own issue.Bundle size
nx run-many -t build -p utils auth protocol sdk plugin-webmcp --skip-nx-cache, thennx test demo-e2e-bundle-size:create()+ one tool, esbuild, minifiedcreate()+ WebMcpPlugin + one toolcreate()+ one toolA page resolves
browser, which this change doesn't touch, so the page bundles don't move.User-facing change
@frontmcp/utils,@frontmcp/authand@frontmcp/protocolgive their Node variants to theworkerdcondition instead ofworker. A browser Web Worker now gets the browser variants, as a page does. This covers webpack'starget: 'webworker', Parcel's workers, and esbuild or Rollup givenworkeralongsidebrowser. Cloudflare Workers built by wrangler or@cloudflare/vite-pluginresolve the same files as before.target: 'webworker',create()failed withprocess is not definedor an unresolved Node built-in. It now starts and serves tools.worker+browserand noworkerdused to get the Node variants and now gets the browser ones. It has to passworkerd, as wrangler does.workerdcondition).frontmcp-deployment/references/build-for-browser.md: Web Workers get the browser builds, Rollup needsbrowser: true, esbuild needsplatform: 'browser', plus a troubleshooting row.frontmcp-deployment/references/deploy-to-cloudflare.md: wrangler's conditions, custom bundlers must passworkerd, plus a troubleshooting row.Tests
apps/e2e/demo-e2e-bundle-size/e2e/browser-web-worker.e2e.spec.ts(new). It bundlescreate()+ one tool as a browser Web Worker twice: with webpacktarget: 'webworker', and with esbuildplatform: 'browser'+conditions: ['worker']. Each bundle is checked for the Node variants of utils, auth and protocol, then run in a worker-like context with noprocess,Buffer,globalorsetImmediate, where the worker posts its tool result.AsyncLocalStorage is not a constructor.node:http2.scripts/worker-export-conditions.test.mjs. For everyimportsandexportsentry of every package underlibs/andplugins/, it checks that a browser Web Worker resolves the file a page resolves, forimportandrequire, with and withoutmodule. It also resolves every split and the utils and auth root exports with the condition sets of Cloudflare (workerd,worker,browser), a browser Web Worker (worker,browser), Vercel Edge (edge-light,browser), a browser and Node.scripts/strip-dist-from-pkg.test.mjs. Its subpath-import fixture maps the Node variant withworkerd, as the packages now do.nx test demo-e2e-bundle-size: 10 suites, 44 tests passed, with the sizes above.nx test demo-e2e-cloudflare: 2 suites, 16 tests passed. One suite is skipped as on the base.node --test scripts/*.test.mjs: 88 passed.node scripts/check-worker-isolate-safety.mjs: clean.nx test utils2,117 passed,auth2,855,protocol9,skills249.nx run-many -t lint -p utils auth protocol skills: no errors.tsc --noEmit -p apps/e2e/demo-e2e-bundle-size/tsconfig.e2e.json: no errors.target: 'web'with and without a worker entry, and Rollup withbrowser: true, without it, and withbrowser: true+exportConditions: ['worker'], each before and after the change.Summary by CodeRabbit
Bug Fixes
Documentation