Add support for custom class instance serialization

[TooTallNate]

Added support for custom class instance serialization across workflow/step boundaries.

What changed?

• Introduced a new @workflow/serde package with WORKFLOW_SERIALIZE and WORKFLOW_DESERIALIZE symbols
• Enhanced the serialization system to handle custom class instances using these symbols
• Updated the SWC plugin to detect classes with serialization methods and register them
• Added class registry mechanism that works in both step and workflow contexts
• Implemented comprehensive tests for various serialization scenarios

How to test?

The PR includes a new e2e test customSerializationWorkflow that demonstrates the feature:

// Define a class with custom serialization
class Point {
  constructor(public x: number, public y: number) {}

  static [WORKFLOW_SERIALIZE](instance: Point) {
    return { x: instance.x, y: instance.y };
  }

  static [WORKFLOW_DESERIALIZE](data: { x: number; y: number }) {
    return new Point(data.x, data.y);
  }
}

// Use in workflow and steps
export async function customSerializationWorkflow(x: number, y: number) {
  'use workflow';
  const point = new Point(x, y);
  const scaled = await transformPoint(point, 2);
  // ...
}

Run the e2e test to verify that class instances are properly serialized and deserialized.

Why make this change?

Previously, user-defined class instances couldn't be passed between workflows and steps without losing their prototype chain and methods. This change allows developers to define custom serialization/deserialization logic for their classes, enabling proper reconstruction of instances with their full functionality intact when crossing workflow/step boundaries.

[changeset-bot]

🦋 Changeset detected

Latest commit: 270db45

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

This PR includes changesets to release 15 packages

Name	Type
@workflow/swc-plugin	Patch
@workflow/core	Patch
@workflow/astro	Patch
@workflow/builders	Patch
@workflow/cli	Patch
@workflow/next	Patch
@workflow/nitro	Patch
@workflow/rollup	Patch
@workflow/sveltekit	Patch
@workflow/docs-typecheck	Patch
@workflow/web-shared	Patch
workflow	Patch
@workflow/world-testing	Patch
@workflow/nuxt	Patch
@workflow/ai	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

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

Project	Deployment	Review	Updated (UTC)
example-nextjs-workflow-turbopack	Ready	Preview, Comment	Jan 14, 2026 10:28pm
example-nextjs-workflow-webpack	Ready	Preview, Comment	Jan 14, 2026 10:28pm
example-workflow	Ready	Preview, Comment	Jan 14, 2026 10:28pm
workbench-astro-workflow	Ready	Preview, Comment	Jan 14, 2026 10:28pm
workbench-express-workflow	Ready	Preview, Comment	Jan 14, 2026 10:28pm
workbench-fastify-workflow	Ready	Preview, Comment	Jan 14, 2026 10:28pm
workbench-hono-workflow	Ready	Preview, Comment	Jan 14, 2026 10:28pm
workbench-nitro-workflow	Ready	Preview, Comment	Jan 14, 2026 10:28pm
workbench-nuxt-workflow	Ready	Preview, Comment	Jan 14, 2026 10:28pm
workbench-sveltekit-workflow	Ready	Preview, Comment	Jan 14, 2026 10:28pm
workbench-vite-workflow	Ready	Preview, Comment	Jan 14, 2026 10:28pm
workflow-docs	Ready	Preview, Comment	Jan 14, 2026 10:28pm

[github-actions]

🧪 E2E Test Results

❌ Some tests failed

Summary

	Passed	Failed	Skipped	Total
✅ ▲ Vercel Production	429	0	11	440
✅ 💻 Local Development	392	0	8	400
✅ 📦 Local Production	392	0	8	400
✅ 🐘 Local Postgres	392	0	8	400
✅ 🪟 Windows	40	0	0	40
❌ 🌍 Community Worlds	150	22	0	172
Total	1795	22	35	1852

❌ Failed Tests

🌍 Community Worlds (22 failed)

mongodb (1 failed):

• webhookWorkflow

redis (1 failed):

• webhookWorkflow

starter (19 failed):

• addTenWorkflow
• addTenWorkflow
• error handling error propagation workflow errors nested function calls preserve message and stack trace
• error handling error propagation workflow errors cross-file imports preserve message and stack trace
• error handling error propagation step errors basic step error preserves message and stack trace
• error handling error propagation step errors cross-file step error preserves message and function names in stack
• error handling retry behavior regular Error retries until success
• error handling retry behavior FatalError fails immediately without retries
• error handling catchability FatalError can be caught and detected with FatalError.is()
• hookCleanupTestWorkflow - hook token reuse after workflow completion
• stepFunctionPassingWorkflow - step function references can be passed as arguments (without closure vars)
• stepFunctionWithClosureWorkflow - step function with closure variables passed as argument
• spawnWorkflowFromStepWorkflow - spawning a child workflow using start() inside a step
• pathsAliasWorkflow - TypeScript path aliases resolve correctly
• Calculator.calculate - static workflow method using static step methods from another class
• AllInOneService.processNumber - static workflow method using sibling static step methods
• ChainableService.processWithThis - static step methods using this to reference the class
• thisSerializationWorkflow - step function invoked with .call() and .apply()
• customSerializationWorkflow - custom class serialization with WORKFLOW_SERIALIZE/WORKFLOW_DESERIALIZE

turso (1 failed):

• webhookWorkflow

Details by Category

✅ ▲ Vercel Production

App	Passed	Failed	Skipped
✅ astro	39	0	1
✅ example	39	0	1
✅ express	39	0	1
✅ fastify	39	0	1
✅ hono	39	0	1
✅ nextjs-turbopack	39	0	1
✅ nextjs-webpack	39	0	1
✅ nitro	39	0	1
✅ nuxt	39	0	1
✅ sveltekit	39	0	1
✅ vite	39	0	1

✅ 💻 Local Development

App	Passed	Failed	Skipped
✅ astro-stable	39	0	1
✅ express-stable	39	0	1
✅ fastify-stable	39	0	1
✅ hono-stable	39	0	1
✅ nextjs-turbopack-stable	40	0	0
✅ nextjs-webpack-stable	40	0	0
✅ nitro-stable	39	0	1
✅ nuxt-stable	39	0	1
✅ sveltekit-stable	39	0	1
✅ vite-stable	39	0	1

✅ 📦 Local Production

App	Passed	Failed	Skipped
✅ astro-stable	39	0	1
✅ express-stable	39	0	1
✅ fastify-stable	39	0	1
✅ hono-stable	39	0	1
✅ nextjs-turbopack-stable	40	0	0
✅ nextjs-webpack-stable	40	0	0
✅ nitro-stable	39	0	1
✅ nuxt-stable	39	0	1
✅ sveltekit-stable	39	0	1
✅ vite-stable	39	0	1

✅ 🐘 Local Postgres

App	Passed	Failed	Skipped
✅ astro-stable	39	0	1
✅ express-stable	39	0	1
✅ fastify-stable	39	0	1
✅ hono-stable	39	0	1
✅ nextjs-turbopack-stable	40	0	0
✅ nextjs-webpack-stable	40	0	0
✅ nitro-stable	39	0	1
✅ nuxt-stable	39	0	1
✅ sveltekit-stable	39	0	1
✅ vite-stable	39	0	1

✅ 🪟 Windows

App	Passed	Failed	Skipped
✅ nextjs-turbopack	40	0	0

❌ 🌍 Community Worlds

App	Passed	Failed	Skipped
✅ mongodb-dev	3	0	0
❌ mongodb	39	1	0
✅ redis-dev	3	0	0
❌ redis	39	1	0
✅ starter-dev	3	0	0
❌ starter	21	19	0
✅ turso-dev	3	0	0
❌ turso	39	1	0

---

📋 View full workflow run

[TooTallNate]

• Add support for "use step" functions in class instance methods #777
• Add support for custom class instance serialization #762 👈 (View in Graphite)
• Add support for serializing this when invoking step functions #754
• Support class static methods with "use step" / "use workflow" #753
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[vercel]

Additional Suggestion:

Global class serialization registry lacks unregister/cleanup mechanism, causing potential test isolation issues and silent overwriting of class registrations

[vercel]

🔧 Build Fix:

MDX syntax error: unexpected character ! before name. The MDX comment syntax is incorrect - comments must use {/* text */} format instead of ! (note: to create a comment in MDX, use {/* text */}).