Skip to content

PATTERN Cited by 1 source

SWC plugin three-mode transform

SWC plugin three-mode transform is the pattern where a single compiler plugin is parameterised by a mode axis and emits different output artefacts depending on the mode, from the same input source file. It lets a cross-framework SDK ship one compiler plugin that produces N deployment artefacts per source file without duplicating plugin logic.

Canonical verbatim

From Vercel's 2026-04-21 WDK post: "The magic happens in WDK's SWC compiler plugin, which transforms the same input file into three different outputs depending on the mode."

"You write your code once, and the compiler generates the client, step handler, and workflow handler automatically."

The three modes in WDK

  1. Client mode — runs during the framework's build via a Rollup or Vite plugin. "Transforms workflow calls into HTTP client code and adds workflowId properties." Produces the user-facing client stub — the shape user code imports to trigger workflows.
  2. Step mode — runs during WDK's esbuild phase. "Transforms \"use step\" functions into HTTP handlers that execute your step logic on the server." Produces the server-side step executor.
  3. Workflow mode — runs during esbuild. "Transforms \"use workflow\" functions into orchestrators that run in a sandboxed virtual environment." Produces the server-side workflow orchestrator.

All three outputs come from the same source file. User writes workflow + step functions once; the compiler rewrites the same code three different ways.

Why mode-parameterised is load-bearing

Without the mode axis, you'd need three separate plugins with duplicated AST-walking code — one to emit client stubs, one to emit step handlers, one to emit orchestrators. Each would drift independently as the language/framework evolves.

With the mode axis, the parse + AST-analysis logic is shared; only the emit path differs by mode. This collapses three plugins to one.

How the modes are invoked

The plugin is invoked in different phases of the build pipeline:

  • Client mode runs during the user's framework build (Rollup plugin hooked into the framework's bundler). The output goes into the user's client-side bundle.
  • Step mode + Workflow mode run during WDK's own esbuild phase — a parallel bundler WDK controls that emits the server-side handler bundles independently of the user's framework bundler.

This parallel-build architecture means the client-side + server-side outputs don't interfere, and the server-side bundles can have a different dependency graph (e.g. no React runtime on server-side step handlers).

Directive-driven

The mode-parameterised transform reads use-directive compilation markers to know which functions to transform:

  • "use workflow" → Workflow mode transforms this function
  • "use step" → Step mode transforms this function
  • Everything else → Client mode rewrites call sites only

Operationalises concepts/build-time-vs-runtime-phase-separation at the build-time phase — the plugin is the entire build-time mechanism in WDK's patterns/two-phase-framework-integration-pattern.

When to use

  • Cross-framework SDK that needs client + server + orchestrator outputs from the same source.
  • When the build-time phase has enough shared logic (parse + AST analysis) to amortise plugin maintenance.
  • When build-phases can run in parallel via different bundlers (Rollup for client, esbuild for server).

Seen in

Last updated · 476 distilled / 1,218 read