How the directives work

Workflows use special directives to mark code for transformation by the Workflow SDK compiler. The "use workflow" and "use step" directives apply the transformations required for durable execution.

Directives overview

Workflows use two directives to mark functions for special handling:

export async function handleUserSignup(email: string) {
  "use workflow";

  const user = await createUser(email);
  await sendWelcomeEmail(user);

  return { userId: user.id };
}

async function createUser(email: string) {
  "use step";

  return { id: crypto.randomUUID(), email };
}

Key directives:

• "use workflow": Marks a function as a durable workflow entry point
• "use step": Marks a function as an atomic, retryable step

These directives trigger the @workflow/swc-plugin compiler to transform your code in different ways depending on the execution context.

The three transformation modes

The compiler operates in three distinct modes, transforming the same source code differently for each execution context:

Comparison table

Detailed transformation examples

export async function createUser(email: string) {
  "use step";
  return { id: crypto.randomUUID(), email };
}

export async function handleUserSignup(email: string) {
  "use workflow";
  const user = await createUser(email);
  return { userId: user.id };
}

export async function createUser(email: string) {
  return { id: crypto.randomUUID(), email };
}
(function(__wf_fn, __wf_id) {
    var __wf_sym = Symbol.for("@workflow/core//registeredSteps"), __wf_reg = globalThis[__wf_sym] || (globalThis[__wf_sym] = new Map());
    __wf_reg.set(__wf_id, __wf_fn);
    __wf_fn.stepId = __wf_id;
})(createUser, "step//workflows/user.js//createUser");

export async function handleUserSignup(email: string) {
  throw new Error("You attempted to execute ...");
}
handleUserSignup.workflowId = "workflow//workflows/user.js//handleUserSignup";

export async function createUser(email: string) {
  "use step";
  return { id: crypto.randomUUID(), email };
}

export async function handleUserSignup(email: string) {
  "use workflow";
  const user = await createUser(email);
  return { userId: user.id };
}

export async function createUser(email: string) {
  return globalThis[Symbol.for("WORKFLOW_USE_STEP")]("step//workflows/user.js//createUser")(email);
}

export async function handleUserSignup(email: string) {
  const user = await createUser(email);
  return { userId: user.id };
}
handleUserSignup.workflowId = "workflow//workflows/user.js//handleUserSignup";

export async function handleUserSignup(email: string) {
  "use workflow";
  const user = await createUser(email);
  return { userId: user.id };
}

/**__internal_workflows{"workflows":{"user.js":{"handleUserSignup":{"workflowId":"workflow//workflows/user.js//handleUserSignup"}}}}*/;
export async function handleUserSignup(email: string) {
  "use workflow";
  const user = await createUser(email);
  return { userId: user.id };
}

Generated files

When you build your application, the Workflow SDK generates a combined flow handler, an internal step registration bundle, and a webhook handler. Exact filenames vary by framework.

flow.js

Contains all workflow functions transformed in workflow mode. This file is imported by your framework to handle workflow execution requests at POST /.well-known/workflow/v1/flow.

How it's structured:

All workflow code is bundled together and embedded as a string inside flow.js. When a workflow needs to execute, this bundled code is run inside a Node.js VM (virtual machine) to ensure:

• Determinism: The same inputs always produce the same outputs
• Side-effect prevention: Direct access to Node.js APIs, the file system, the network, and other resources is blocked
• Sandboxed execution: Workflow orchestration logic is isolated from the main runtime

Build-time validation:

The workflow mode transformation validates your code during the build:

• Catches invalid Node.js API usage (like fs, http, child_process)
• Prevents imports of modules that would break determinism

Most invalid patterns cause build-time errors, catching issues before deployment.

What it does:

• Exports a POST handler that accepts Web standard Request objects
• Executes bundled workflow code inside a Node.js VM for each request
• Handles workflow execution, replay, and resumption
• Returns execution results to the orchestration layer

__step_registrations.js

Contains all step functions transformed in step mode. The combined flow handler imports this module for its registration side effects.

What it does:

• Adds step functions to the runtime step registry
• Keeps step bodies in the full host runtime
• Makes registered steps available when a flow queue message includes stepId and stepName

This module must not be exposed as an HTTP endpoint.

webhook.js

Contains webhook handling logic for delivering external data to running workflows via createWebhook().

What it does:

• Exports a POST handler that accepts webhook payloads
• Validates tokens and routes data to the correct workflow run
• Resumes workflow execution after webhook delivery

The webhook file structure varies by framework. Next.js generates webhook/[token]/route.js to use App Router's dynamic routing, while other frameworks generate a single webhook.js or webhook.mjs handler.

Why three modes?

The multi-mode transformation enables the Workflow SDK's durable execution model:

1. Step mode (required): Bundles executable step functions that can access the full runtime and serves as the application-code transform that prevents direct workflow execution and enables type-safe start() references
2. Workflow mode (required): Creates orchestration logic that can replay from event logs
3. Detect mode (build-internal): Discovers directive-marked functions for the build without changing the code

This separation allows:

• Deterministic replay: Workflows can be safely replayed from event logs without re-executing side effects
• Sandboxed orchestration: Workflow logic runs in a controlled VM without direct runtime access
• Stateless execution: Your compute can scale to zero and resume from any point in the workflow
• Type safety: TypeScript supports workflow references passed to start()

Determinism and replay

A key aspect of the transformation is maintaining deterministic replay for workflow functions.

Workflow functions must be deterministic:

• Same inputs always produce the same outputs
• No direct side effects (no API calls, no database writes, no file I/O)
• Can use seeded random/time APIs provided by the VM (Math.random(), Date.now(), etc.)

Because workflow functions are deterministic and have no side effects, they can be safely rerun multiple times to calculate the next step. Workflow function bodies remain intact in workflow mode because they're pure orchestration logic.

Step functions can be non-deterministic:

• Can make API calls, database queries, etc.
• Have full access to Node.js runtime and APIs
• Results are cached in the event log after first execution

Learn more about Workflows and Steps.

ID generation

The compiler generates stable IDs for workflows and steps based on file paths and function names:

Pattern: {type}//{filepath}//{functionName}

Examples:

• workflow//workflows/user-signup.js//handleUserSignup
• step//workflows/user-signup.js//createUser
• step//workflows/payments/checkout.ts//processPayment

Key properties:

• Stable: IDs don't change unless you rename files or functions
• Unique: Each workflow/step has a unique identifier
• Portable: Works across different runtimes and deployments

Framework integration

These transformations are framework-agnostic. They output standard JavaScript that works anywhere.

For users: Your framework handles all transformations automatically. See the Getting Started guide for your framework.

For framework authors: Learn how to integrate these transformations into your framework in Building Framework Integrations.

Debugging transformed code

If you need to debug transformation issues, you can inspect the generated files:

1. Inspect the generated output: Check the combined flow handler, step registration bundle, webhook handler, and emitted debug files.
2. Check build logs: Most frameworks log transformation activity during builds
3. Verify directives: Ensure "use workflow" and "use step" are the first statements in functions
4. Check file locations: Transformations only apply to files in configured source directories