Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/eersnington/sideffect/llms.txt

Use this file to discover all available pages before exploring further.

WorkflowEngine is the low-level runtime bridge that connects Sideffect workflow layers to the Cloudflare Workers runtime. Most users will never call it directly — it is used internally by WorkflowEntrypoints.make() and by the Vite-generated virtual:sideffect/entry module. Import it from sideffect.
WorkflowEngine is an advanced API whose interface may change without a deprecation cycle. It exists primarily to support generated code and internal adapters. Unless you are writing a custom WorkflowEntrypoint subclass, building a test harness, or authoring a Sideffect plugin, use WorkflowEntrypoints.make() or withCloudflareWorkflows() instead.
You might reach for WorkflowEngine directly when:
  • Writing a custom WorkflowEntrypoint subclass that needs to delegate to a Sideffect layer without going through WorkflowEntrypoints.make().
  • Writing unit or integration tests that exercise workflow execution without a full Vite setup.
  • Building a plugin or adapter that needs explicit control over NonRetryableError conversion.

​
WorkflowEngine.make()

Creates a named WorkflowEntrypoint subclass constructor that wraps a single Sideffect layer. This is the lower-level primitive that WorkflowEntrypoints.make() calls for each entry.

​
Function signature

WorkflowEngine.make(
  exportName: string,
  layer: WorkflowLayerAny,
  WorkflowEntrypoint: WorkflowEntrypointConstructor,
  makeOptions?: { NonRetryableError?: NonRetryableErrorConstructor },
): WorkflowEntrypointConstructor

​
Parameters

​
exportName
string
required
The export name and class name for the generated entrypoint class. Must be a valid JavaScript identifier — the same constraint imposed by WorkflowEntrypoints.make(). Cloudflare’s runtime uses this name to match against the class_name in your Wrangler workflow binding config.
​
layer
WorkflowLayerAny
required
The Sideffect workflow layer to bind to the generated entrypoint. Created by Workflow.make(...).toLayer(...).
​
WorkflowEntrypoint
WorkflowEntrypointConstructor
required
The Cloudflare WorkflowEntrypoint base class imported from cloudflare:workers. Sideffect accepts this as a parameter instead of importing it directly so that the core sideffect package does not take a hard dependency on cloudflare:workers (which is only available inside the Cloudflare Workers runtime).
import { WorkflowEntrypoint } from "cloudflare:workers";
​
makeOptions.NonRetryableError
NonRetryableErrorConstructor
The Cloudflare native NonRetryableError constructor from cloudflare:workflows. When provided, Sideffect converts its own portable NonRetryableError instances to the native Cloudflare version at the workflow boundary. If omitted, portable NonRetryableError instances are still treated as non-retryable by the Workers SDK based on error name matching, but native conversion does not occur.
import { NonRetryableError } from "cloudflare:workflows";

​
Return value

​
WorkflowEntrypointConstructor
class
A WorkflowEntrypoint subclass whose run(event, step) method delegates to WorkflowEngine.run(layer, { ... }). The class is named using a computed property key so that constructor.name === exportName.

​
Example

import { WorkflowEntrypoint } from "cloudflare:workers";
import { NonRetryableError } from "cloudflare:workflows";
import { WorkflowEngine } from "sideffect";
import { resizeImageLayer } from "./workflows/resize-image";

export const ResizeImage = WorkflowEngine.make(
  "ResizeImage",
  resizeImageLayer,
  WorkflowEntrypoint,
  { NonRetryableError },
);

​
WorkflowEngine.run()

Executes a Sideffect workflow layer with a native Cloudflare workflow event and step API. This is the method called by the generated run(event, step) inside every entrypoint class produced by WorkflowEngine.make().

​
Function signature

WorkflowEngine.run<Result>(
  layer: WorkflowLayerAny,
  options: EngineRunOptions,
): Promise<Result>

​
Parameters

​
layer
WorkflowLayerAny
required
The Sideffect workflow layer to execute.
​
options.env
unknown
required
The Worker environment bindings object from the WorkflowEntrypoint instance (this.env). Passed through to the layer’s run function and to every step callback as context.env.
​
options.ctx
unknown
required
The Worker execution context from the WorkflowEntrypoint instance (this.ctx). Passed through to the layer’s run function and to every step callback as context.ctx.
​
options.event
CloudflareWorkflowEventAny
required
The raw Cloudflare workflow event object before Sideffect decodes the payload. The payload field on the event is the untyped value as received from the Cloudflare runtime; WorkflowEngine.run() decodes it using the layer’s payloadSchema before passing it to the layer’s run function.
​
options.step
NativeWorkflowStep
required
The native Cloudflare WorkflowStep API object passed to WorkflowEntrypoint.run() by the Cloudflare runtime. Sideffect wraps it with a SideffectStep façade that adds typed payload and result decoding for step.do() calls.
​
options.NonRetryableError
NonRetryableErrorConstructor
Optional Cloudflare native NonRetryableError constructor from cloudflare:workflows. When provided, any Sideffect NonRetryableError thrown by the layer or its steps is converted to the native version before propagating to the Cloudflare runtime.

​
Return value

​
Promise<Result>
Promise
A promise that resolves with the return value of the layer’s run function. The return type is inferred from the layer’s WorkflowLayer<Payload, Result> type parameters.If the layer throws a Sideffect NonRetryableError and options.NonRetryableError was provided, the promise rejects with the native Cloudflare NonRetryableError — causing the Cloudflare runtime to mark the workflow as failed without retrying. Any other thrown error propagates unchanged.

​
Example

The following shows a custom WorkflowEntrypoint that calls WorkflowEngine.run() directly, giving you the option to inject custom logic before and after workflow execution: 
import { WorkflowEntrypoint } from "cloudflare:workers";
import { NonRetryableError } from "cloudflare:workflows";
import { WorkflowEngine } from "sideffect";
import { resizeImageLayer } from "./workflows/resize-image";

export class ResizeImage extends WorkflowEntrypoint {
  async run(event, step) {
    console.log("Workflow started:", event.id);

    const result = await WorkflowEngine.run(resizeImageLayer, {
      env: this.env,
      ctx: this.ctx,
      event,
      step,
      NonRetryableError,
    });

    console.log("Workflow finished:", result);
    return result;
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us