Uh oh!
There was an error while loading. Please reload this page.
Add CommonJS require() support for class serialization detection in SWC plugin - #1144
Merged
TooTallNate merged 3 commits intoMar 23, 2026
Conversation
🦋 Changeset detectedLatest commit: 14ea197 The changes in this PR will be included in the next version bump. This PR includes changesets to release 17 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
Contributor
Contributor
🧪 E2E Test Results❌ Some tests failed Summary
❌ Failed Tests🌍 Community Worlds (56 failed)mongodb (3 failed):
redis (2 failed):
turso (51 failed):
Details by Category✅ ▲ Vercel Production
✅ 💻 Local Development
✅ 📦 Local Production
✅ 🐘 Local Postgres
✅ 🪟 Windows
❌ 🌍 Community Worlds
✅ 📋 Other
|
Contributor
📊 Benchmark Results
workflow with no steps💻 Local Development
workflow with 1 step💻 Local Development
workflow with 10 sequential steps💻 Local Development
workflow with 25 sequential steps💻 Local Development
workflow with 50 sequential steps💻 Local Development
Promise.all with 10 concurrent steps💻 Local Development
Promise.all with 25 concurrent steps💻 Local Development
Promise.all with 50 concurrent steps💻 Local Development
Promise.race with 10 concurrent steps💻 Local Development
Promise.race with 25 concurrent steps💻 Local Development
Promise.race with 50 concurrent steps💻 Local Development
workflow with 10 sequential data payload steps (10KB)💻 Local Development
workflow with 25 sequential data payload steps (10KB)💻 Local Development
workflow with 50 sequential data payload steps (10KB)💻 Local Development
workflow with 10 concurrent data payload steps (10KB)💻 Local Development
workflow with 25 concurrent data payload steps (10KB)💻 Local Development
workflow with 50 concurrent data payload steps (10KB)💻 Local Development
Stream Benchmarks(includes TTFB metrics)workflow with stream💻 Local Development
stream pipeline with 5 transform steps (1MB)💻 Local Development
10 parallel streams (1MB each)💻 Local Development
fan-out fan-in 10 streams (1MB each)💻 Local Development
SummaryFastest Framework by WorldWinner determined by most benchmark wins
Fastest World by FrameworkWinner determined by most benchmark wins
Column Definitions
Worlds:
❌ Some benchmark jobs failed:
Check the workflow run for details. |
TooTallNate
commented
Feb 20, 2026
MemberAuthor
This stack of pull requests is managed by Graphite. Learn more about stacking. |
Contributor
There was a problem hiding this comment.
Pull request overview
This PR extends the @workflow/swc-plugin transform to detect custom class serialization methods when the WORKFLOW_SERIALIZE / WORKFLOW_DESERIALIZE symbols are accessed via CommonJS require() patterns, aligning behavior with codebases that have been transpiled from ESM to CJS.
Changes:
- Track CommonJS
require()bindings during identifier collection (namespaceconst x = require(...)and destructuredconst { ... } = require(...)) and recognizex.WORKFLOW_SERIALIZE/x.WORKFLOW_DESERIALIZEas serialization symbols. - Add fixture coverage for both namespace-require and destructured-require inputs across workflow/step/client outputs.
- Update the plugin spec and add a changeset entry documenting the new behavior.
Reviewed changes
Copilot reviewed 11 out of 11 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| packages/swc-plugin-workflow/transform/src/lib.rs | Adds require-binding tracking and member-expression symbol recognition for serialization detection. |
| packages/swc-plugin-workflow/transform/tests/fixture/custom-serialization-require-namespace/input.js | New fixture input for namespace require() pattern. |
| packages/swc-plugin-workflow/transform/tests/fixture/custom-serialization-require-namespace/output-workflow.js | Expected workflow-mode output for namespace require() fixture. |
| packages/swc-plugin-workflow/transform/tests/fixture/custom-serialization-require-namespace/output-step.js | Expected step-mode output for namespace require() fixture. |
| packages/swc-plugin-workflow/transform/tests/fixture/custom-serialization-require-namespace/output-client.js | Expected client-mode output for namespace require() fixture. |
| packages/swc-plugin-workflow/transform/tests/fixture/custom-serialization-require-destructured/input.js | New fixture input for destructured require() pattern. |
| packages/swc-plugin-workflow/transform/tests/fixture/custom-serialization-require-destructured/output-workflow.js | Expected workflow-mode output for destructured require() fixture. |
| packages/swc-plugin-workflow/transform/tests/fixture/custom-serialization-require-destructured/output-step.js | Expected step-mode output for destructured require() fixture. |
| packages/swc-plugin-workflow/transform/tests/fixture/custom-serialization-require-destructured/output-client.js | Expected client-mode output for destructured require() fixture. |
| packages/swc-plugin-workflow/spec.md | Documents supported CommonJS require() symbol patterns. |
| .changeset/social-forks-tease.md | Declares a patch release for the new detection behavior. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
This was referenced Mar 22, 2026
…WC plugin
The SWC compiler plugin now detects classes with custom serialization methods (`WORKFLOW_SERIALIZE` / `WORKFLOW_DESERIALIZE`) when symbols are obtained via CommonJS `require()` calls, in addition to the existing ESM import and `Symbol.for()` patterns.
This handles code that has been pre-compiled from ESM to CommonJS by tools like TypeScript (tsc), esbuild, or tsup, which transform:
```ts
import { WORKFLOW_SERIALIZE } from "@workflow/serde"
```
into either:
```ts
const serde_1 = require("@workflow/serde") // namespace require
const { WORKFLOW_SERIALIZE } = require(...) // destructured require
```
Both patterns are now recognized during the identifier collection phase, and classes using them are properly registered with registerSerializationClass().require() support for class serialization detection in SWC plugin…on_bindings helper - Tighten is_require_call to require exactly one string literal argument, rejecting dynamic requires and multi-arg calls. - Extract track_serialization_bindings helper to deduplicate the require tracking logic between Decl::Var and ExportDecl(Decl::Var) branches.
TooTallNateforce-pushed
the
02-20-add_commonjs_require_support_for_class_serialization_detection_in_swc_plugin
branch
from
March 23, 2026 14:01
3648e46 to
f461c59Compare…_serialization_detection_in_swc_plugin
VaguelySerious
approved these changes
Mar 23, 2026
Uh oh!
There was an error while loading. Please reload this page.
TooTallNate
deleted the
02-20-add_commonjs_require_support_for_class_serialization_detection_in_swc_plugin
branch
March 23, 2026 18:30
pranaygp
left a comment
Contributor
There was a problem hiding this comment.
Post-merge review — overall this is a clean, well-tested addition. A few observations below.
| // Track CommonJS namespace require: const serde_1 = require("...") | ||
| if self.is_require_call(init) { | ||
| self.require_namespace_identifiers | ||
| .insert(ident.id.sym.to_string()); |
Contributor
There was a problem hiding this comment.
Nit: This tracks everyrequire() call as a namespace identifier, regardless of the module being required. So const fs = require("fs") would cause fs.WORKFLOW_SERIALIZE to be treated as a serialization symbol if it ever appeared. This is unlikely to cause real bugs since nobody would name a property WORKFLOW_SERIALIZE on an unrelated module, but it is semantically imprecise.
Consider either:
- Restricting to known serde modules (e.g. checking the string arg contains
@workflow/serdeor similar), or - Documenting this as an intentional trade-off (broad tracking is simpler and the false-positive risk is negligible).
| match prop { | ||
| ObjectPatProp::Assign(assign) => { | ||
| // const { WORKFLOW_SERIALIZE } = require("...") | ||
| let name = assign.key.sym.to_string(); |
Contributor
There was a problem hiding this comment.
Nit: The ObjectPatProp::Assign arm handles const { WORKFLOW_SERIALIZE } = require(...), but in the SWC AST this node actually represents const { WORKFLOW_SERIALIZE = defaultValue } = require(...) (a destructured binding with a default value). A plain shorthand const { WORKFLOW_SERIALIZE } = require(...) is typically parsed as ObjectPatProp::KeyValue where key and value ident are the same.
In practice this still works because SWC may represent the no-default shorthand either way depending on version, and the logic is correct for both paths. But worth noting that the Assign arm would also match const { WORKFLOW_SERIALIZE = someDefault } = require(...), which is an unusual but technically valid pattern.
| @@ -0,0 +1,25 @@ | |||
| // Test custom serialization with CommonJS destructured require | |||
| const { WORKFLOW_SERIALIZE, WORKFLOW_DESERIALIZE } = require("@workflow/serde"); | |||
Contributor
There was a problem hiding this comment.
The spec documents renamed destructured require (const { WORKFLOW_SERIALIZE: WS } = require(...)) but there's no test fixture covering this case. Adding a custom-serialization-require-destructured-renamed fixture would ensure the ObjectPatProp::KeyValue branch stays correct.
pranaygp added a commit
that referenced
this pull request
Mar 23, 2026
* origin/main: [ai] Add experimental_context to DurableAgentOptions (#1489) [ai] Expose configured tools on DurableAgent instances (#1488) fix(builders): catch node builtin usage when entry fields diverge (#1455) [web-shared] Fix timeline duration format and precision (#1482) [cli] Add bulk cancel, --status filter, fix step JSON hydration (#1467) [utils] Re-export parseName utilities and add workflow/observability module (#1453) [o11y] Polish display when run data has expired (#1438) Add CommonJS `require()` support for class serialization detection in SWC plugin (#1144) fix(next): stabilize deferred canary e2e in nextjs workbenches (#1468) [web] Support legacy newline-delimited stream format in `useStreamReader` (#1473) Revert "Add support for calling start() inside workflow functions (#1133)" (#1475)
pranaygp added a commit
that referenced
this pull request
Mar 24, 2026
…naygp-db9e68c1 * 'main' of https://github.com/vercel/workflow: (32 commits) chore: bump @nestjs/* to ^11.1.17 (#1497) chore: bump hono to ^4.12.8 (#1495) Revert "Inline class serialization registration to fix 3rd-party package supp…" (#1493) [world] Add stream pagination and metadata endpoints (#1470) [cli] [world-local] Ensure update checks don't suggest upgrading from stable release to pre-releases (#1490) Remove NestJS Vercel integration while in experimental phase (#1485) feat: export semantic error types and add API reference docs (#1447) feat: enforce max queue deliveries in handlers with graceful failure (#1344) [world-postgres] Migrate client from `postgres.js` to `pg` (#1484) Inline class serialization registration to fix 3rd-party package support (#1480) [ai] Add experimental_context to DurableAgentOptions (#1489) [ai] Expose configured tools on DurableAgent instances (#1488) fix(builders): catch node builtin usage when entry fields diverge (#1455) [web-shared] Fix timeline duration format and precision (#1482) [cli] Add bulk cancel, --status filter, fix step JSON hydration (#1467) [utils] Re-export parseName utilities and add workflow/observability module (#1453) [o11y] Polish display when run data has expired (#1438) Add CommonJS `require()` support for class serialization detection in SWC plugin (#1144) fix(next): stabilize deferred canary e2e in nextjs workbenches (#1468) [web] Support legacy newline-delimited stream format in `useStreamReader` (#1473) ...
TooTallNate added a commit
that referenced
this pull request
Mar 24, 2026
The original PR #1480 was merged but reverted because it didn't include updated fixtures for the CJS require patterns added by PR #1144 (custom-serialization-require-destructured and custom-serialization-require-namespace). These fixtures still had the old 'import { registerSerializationClass }' pattern instead of the new inline IIFE.
TooTallNate added a commit
that referenced
this pull request
Mar 24, 2026
…ort (v2) (#1503) * Inline class serialization registration to fix 3rd-party package support (#1480) * Inline class serialization registration to fix 3rd-party package support The SWC plugin previously generated: import { registerSerializationClass } from "workflow/internal/class-serialization"; registerSerializationClass("class//...", ClassName); This broke for 3rd-party packages (e.g. @vercel/sandbox) that define serializable classes but don't depend on the 'workflow' package. The bare 'workflow' specifier is unresolvable from within node_modules of a package that doesn't list it as a dependency. Now the plugin generates a self-contained IIFE that uses Symbol.for('workflow-class-registry') on globalThis directly, with zero module dependencies: (function(__wf_cls, __wf_id) { var __wf_sym = Symbol.for("workflow-class-registry"), __wf_reg = globalThis[__wf_sym] || (globalThis[__wf_sym] = new Map()); __wf_reg.set(__wf_id, __wf_cls); Object.defineProperty(__wf_cls, "classId", { ... }); })(ClassName, "class//..."); This is fully compatible with the existing deserialization side in @workflow/core which reads from the same globalThis registry. * Address review feedback: fix comment and update docstring - Fix inaccurate IIFE comment in lib.rs: the second arg is the generated class ID string, not the literal "classId" - Update registerSerializationClass docstring to reflect that the SWC plugin now inlines equivalent logic rather than importing it * Update CJS require fixture outputs for inline class serialization The original PR #1480 was merged but reverted because it didn't include updated fixtures for the CJS require patterns added by PR #1144 (custom-serialization-require-destructured and custom-serialization-require-namespace). These fixtures still had the old 'import { registerSerializationClass }' pattern instead of the new inline IIFE.
pranaygp pushed a commit
to vercel/sandbox
that referenced
this pull request
Mar 27, 2026
…ibility (#109) ## Summary Makes `@vercel/sandbox` fully compatible with the Workflow DevKit compiler so that `Sandbox`, `Command`, and `CommandFinished` instances can be used directly inside `"use workflow"` functions — no wrapper step functions needed. Supersedes #58. ## Problem When `@vercel/sandbox` is imported in a workflow context, the workflow builder tries to bundle it into the workflow VM bundle (because it has `WORKFLOW_SERIALIZE`/`WORKFLOW_DESERIALIZE` on its classes). This fails because: 1. The SDK's public methods use Node.js APIs (`fs`, `stream`, `zlib`, `undici`, etc.) which are forbidden in the workflow VM 2. The compiled `dist/index.js` was a single bundled file that hoisted all Node.js imports to the top, making them impossible to tree-shake 3. The `Sandbox` and `Command` classes had a sync `client` getter that directly referenced `APIClient`, pulling the entire HTTP client stack into the module scope ## Solution ### 1. `"use step"` annotations on all public async methods Added `"use step"` to all 22 public async methods across `Sandbox` (14), `Command` (5), and `Snapshot` (3). The SWC plugin strips these method bodies in workflow mode, replacing them with durable step proxies. This eliminates all Node.js API references from the workflow bundle. ### 2. Async `ensureClient()` replaces sync `client` getter The sync `get client()` getter directly referenced `APIClient`, which pulls in `undici`, `zlib`, `tar-stream`, `jsonlines`, etc. Replaced with: ```typescript private async ensureClient(): Promise<APIClient> { "use step"; if (this._client) return this._client; const credentials = getSandboxCredentials(); this._client = new APIClient({ ... }); return this._client; } ``` Since `ensureClient()` is itself `"use step"`, its body (including `new APIClient(...)`) gets stripped in workflow mode. All instance methods now call `const client = await this.ensureClient();` instead of `this.client`. ### 3. `bundle: false` in tsdown config Changed from single-file bundling to per-file output. This keeps Node.js imports local to the files that use them, so after the SWC plugin strips step method bodies, the now-unused Node.js imports can be eliminated by esbuild's tree-shaking. ### 4. Workflow-code-runner example updated - Removed `serverExternalPackages: ["@vercel/sandbox"]` from `next.config.ts` (no longer needed) - Updated `workflow` dependency to use a tarball that includes the inline class serialization registration fix (vercel/workflow#1480) ## Testing - `pnpm build` succeeds for the full monorepo (all 8 tasks) - The `workflow-code-runner` example app builds successfully with all workflow routes generated - 22 `"use step"` directives survive compilation in both ESM and CJS dist output ## Related - vercel/workflow#1480 — Inline class serialization registration (fixes SWC import resolution for 3rd-party packages) - vercel/workflow#1481 — Build-time warning when `serverExternalPackages` hides workflow-enabled packages - vercel/workflow#1144 — CJS detection for serde symbols (pending review) - #58 — Previous attempt (superseded by this PR) --------- Signed-off-by: Peter Wielander <mittgfu@gmail.com> Co-authored-by: Peter Wielander <mittgfu@gmail.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The SWC compiler plugin now detects classes with custom serialization methods (
WORKFLOW_SERIALIZE/WORKFLOW_DESERIALIZE) when symbols are obtained via CommonJSrequire()calls, in addition to the existing ESM import andSymbol.for()patterns.This handles code that has been pre-compiled from ESM to CommonJS by tools like TypeScript (tsc), esbuild, or tsup, which transform:
into either:
Both patterns are now recognized during the identifier collection phase, and classes using them are properly registered with registerSerializationClass().