feat(workflow-core): add createWorkflowFactory

.changeset/workflow-factory.md

@@ -0,0 +1,23 @@
+---
+'@tanstack/workflow-core': minor
+---
+
+Add `createWorkflowFactory` for sharing middleware and step-retry defaults across a family of workflows.
+
+```ts
+import { createWorkflowFactory } from '@tanstack/workflow-core'
+
+const appWorkflow = createWorkflowFactory({
+  defaultStepRetry: { maxAttempts: 3 },
+}).middleware([traced, requireUser])
+
+const onboard = appWorkflow({ id: 'onboard' })
+  .middleware([requireEmailVerified]) // appended after factory mws
+  .handler(async (ctx) => {
+    /* ctx.trace, ctx.user, ctx.emailVerified */
+  })
+```
+
+Factory middleware runs before per-workflow middleware; ctx extensions accumulate across both layers. Per-workflow config wins over factory defaults. `appWorkflow.extend({ ... })` forks a child factory with override defaults without mutating the parent.
+
+See [docs/concepts/middleware.md](https://github.com/TanStack/workflow/blob/main/docs/concepts/middleware.md#recipe-share-middleware-across-a-family-of-workflows).

docs/concepts/middleware.md

@@ -81,9 +81,38 @@ async function sendReceipt(
 
 Pass the typed `ctx` to the helper — the constraint documents which middleware fields must be in scope.
 
+## Recipe: share middleware across a family of workflows
+
+Use `createWorkflowFactory` to pin shared middleware and defaults so every workflow in an app gets them without repeating `.middleware([...])` in each file.
+
+```ts
+import { createWorkflowFactory } from '@tanstack/workflow-core'
+
+export const appWorkflow = createWorkflowFactory({
+  defaultStepRetry: { maxAttempts: 3 },
+}).middleware([traced, requireUser])
+
+export const onboard = appWorkflow({ id: 'onboard' })
+  .middleware([requireEmailVerified])  // appended after factory mws
+  .handler(async (ctx) => {
+    ctx.trace; ctx.user; ctx.emailVerified  // all visible
+  })
+```
+
+Factory middleware runs first, then per-workflow middleware, then the handler. Per-workflow config wins over factory defaults when both are set.
+
+Fork a child factory with `.extend()` to layer extra middleware (and optionally override defaults) without mutating the parent:
+
+```ts
+export const paidWorkflow = appWorkflow
+  .extend({ defaultStepRetry: { maxAttempts: 5 } })
+  .middleware([requirePro])
+```
+
 ## Rules
 
 - `.middleware([a, b])` runs `a` first, then `b`, then the handler.
+- Factory middleware (`createWorkflowFactory().middleware([...])`) runs before any per-workflow middleware.
 - Each middleware must call `next()` exactly once. Twice throws `RUN_ERRORED`.
 - Middleware extensions cannot shadow reserved ctx fields (`input`, `state`, `runId`, `signal`, `step`, `sleep`, `sleepUntil`, `waitForEvent`, `approve`, `now`, `uuid`, `emit`). Type system rejects them; runtime guards too.
 

docs/quick-start.md

@@ -117,6 +117,24 @@ const wf = createWorkflow({ id: 'send-receipt' })
 
 Specify the extension type as the generic on `.server<...>` — TS infers everything else.
 
+## Recipe: factory for shared middleware
+
+When several workflows want the same middleware + step-retry defaults, pin them with `createWorkflowFactory`:
+
+```ts
+import { createWorkflowFactory } from '@tanstack/workflow-core'
+
+export const appWorkflow = createWorkflowFactory({
+  defaultStepRetry: { maxAttempts: 3 },
+}).middleware([traced, requireUser])
+
+export const onboard = appWorkflow({ id: 'onboard' })
+  .middleware([requireEmailVerified])     // appended after factory mws
+  .handler(async (ctx) => { /* ctx.trace, ctx.user, ctx.emailVerified */ })
+```
+
+Factory middleware runs before per-workflow middleware. Per-workflow config wins over factory defaults. Use `appWorkflow.extend({ ... })` to fork a child factory with override defaults.
+
 ## Recipe: cross-version resume
 
 ```ts

packages/workflow-core/README.md

@@ -48,7 +48,7 @@ for await (const event of runWorkflow({
 | `ctx.now()` / `ctx.uuid()`             | `Promise<number / string>` | deterministic recorded values                                 |
 | `ctx.emit(name, value)`                | `void`                     | observability-only custom event                               |
 
-Middleware can add more.
+Middleware can add more. Use [`createWorkflowFactory`](../../docs/concepts/middleware.md#recipe-share-middleware-across-a-family-of-workflows) to pin shared middleware and step-retry defaults across a family of workflows.
 
 ## Pause and resume
 

packages/workflow-core/src/define/create-workflow-factory.ts

@@ -0,0 +1,131 @@
+import { createWorkflow } from './define-workflow'
+import type {
+  AccumulateExtensions,
+  CreateWorkflowConfig,
+  WorkflowBuilder,
+} from './define-workflow'
+import type { AnyMiddleware, SchemaInput, StepRetryOptions } from '../types'
+
+// ============================================================
+// Public configuration shape
+// ============================================================
+
+/**
+ * Defaults a factory pre-sets on every workflow it produces.
+ * Per-workflow config wins when both are present.
+ */
+export interface CreateWorkflowFactoryConfig {
+  /** Default retry policy applied to every `ctx.step()` call that
+   *  doesn't carry its own `{ retry }` option. */
+  defaultStepRetry?: StepRetryOptions
+}
+
+// ============================================================
+// Builder type — callable hybrid with chain methods
+// ============================================================
+
+/**
+ * A workflow factory. Calling it returns a `WorkflowBuilder` with
+ * the factory's middlewares pre-applied and config defaults merged.
+ * Chain `.middleware([...])` to layer in shared middleware;
+ * `.extend()` to fork a child factory without mutating the parent.
+ */
+export interface WorkflowFactoryBuilder<TCtxExt = unknown> {
+  /**
+   * Append middlewares to the factory. They run *before* any
+   * middleware registered on the produced workflow, in declaration
+   * order, then the workflow's own middlewares, then the handler.
+   */
+  middleware: <const TMiddlewares extends ReadonlyArray<AnyMiddleware>>(
+    middlewares: TMiddlewares,
+  ) => WorkflowFactoryBuilder<TCtxExt & AccumulateExtensions<TMiddlewares>>
+
+  /**
+   * Fork a child factory with the same middlewares + defaults.
+   * Pass overrides to shallow-merge new defaults onto the child.
+   * The parent is not mutated.
+   */
+  extend: (
+    overrides?: CreateWorkflowFactoryConfig,
+  ) => WorkflowFactoryBuilder<TCtxExt>;
+
+  /**
+   * Produce a workflow builder with the factory's state applied.
+   * The returned builder still supports `.middleware([...])` for
+   * per-workflow middlewares whose ctx extensions are appended to
+   * the factory's.
+   */
+  <
+    TInputSchema extends SchemaInput | undefined = undefined,
+    TOutputSchema extends SchemaInput | undefined = undefined,
+    TStateSchema extends SchemaInput | undefined = undefined,
+  >(
+    config: CreateWorkflowConfig<TInputSchema, TOutputSchema, TStateSchema>,
+  ): WorkflowBuilder<TInputSchema, TOutputSchema, TStateSchema, TCtxExt>
+}
+
+// ============================================================
+// Implementation
+// ============================================================
+
+interface InternalFactoryState {
+  middlewares: ReadonlyArray<AnyMiddleware>
+  defaults: CreateWorkflowFactoryConfig
+}
+
+function buildFactory(
+  state: InternalFactoryState,
+): WorkflowFactoryBuilder<any> {
+  const factory = ((config: CreateWorkflowConfig<any, any, any>) => {
+    const merged: CreateWorkflowConfig<any, any, any> = {
+      ...config,
+      defaultStepRetry:
+        config.defaultStepRetry ?? state.defaults.defaultStepRetry,
+    }
+    const base = createWorkflow(merged)
+    return state.middlewares.length > 0
+      ? base.middleware(state.middlewares)
+      : base
+  }) as WorkflowFactoryBuilder<any>
+
+  factory.middleware = ((middlewares: ReadonlyArray<AnyMiddleware>) =>
+    buildFactory({
+      ...state,
+      middlewares: [...state.middlewares, ...middlewares],
+    })) as WorkflowFactoryBuilder<any>['middleware']
+
+  factory.extend = (overrides) =>
+    buildFactory({
+      middlewares: [...state.middlewares],
+      defaults: { ...state.defaults, ...overrides },
+    })
+
+  return factory
+}
+
+/**
+ * Build a workflow factory. Use it to pin shared middleware and
+ * defaults across a family of workflows:
+ *
+ *     export const appWorkflow = createWorkflowFactory({
+ *       defaultStepRetry: { maxAttempts: 3 },
+ *     }).middleware([traced, requireUser])
+ *
+ *     export const onboard = appWorkflow({ id: 'onboard' })
+ *       .middleware([requireEmailVerified])  // appended after factory mws
+ *       .handler(async (ctx) => {
+ *         ctx.trace; ctx.user; ctx.emailVerified  // all visible
+ *       })
+ *
+ * Factories compose. Derive a specialized child without mutating
+ * the parent — `.extend()` accepts default overrides:
+ *
+ *     export const paidWorkflow = appWorkflow
+ *       .extend({ defaultStepRetry: { maxAttempts: 5 } })
+ *       .middleware([requirePro])
+ */
+export function createWorkflowFactory(
+  config: CreateWorkflowFactoryConfig = {},
+): WorkflowFactoryBuilder<unknown> {
+  return buildFactory({ middlewares: [], defaults: config })
+}

packages/workflow-core/src/index.ts

@@ -6,6 +6,11 @@ export type {
   CreateWorkflowConfig,
   WorkflowBuilder,
 } from './define/define-workflow'
+export { createWorkflowFactory } from './define/create-workflow-factory'
+export type {
+  CreateWorkflowFactoryConfig,
+  WorkflowFactoryBuilder,
+} from './define/create-workflow-factory'
 
 // ===== Middleware =====
 export { createMiddleware } from './middleware/create-middleware'