chore: Backend HMR (expriemental) (#14074)

**What**

 This PR introduces experimental Hot Module Replacement (HMR) for the Medusa backend, enabling developers to see code changes reflected immediately without restarting the server. This significantly improves the development experience by reducing iteration time.

### Key Features

  - Hot reload support for:
    - API Routes
    - Workflows & Steps
    - Scheduled Jobs
    - Event Subscribers
    - Modules
  - IPC-based architecture: The dev server runs in a child process, communicating with the parent watcher via IPC. When HMR fails, the child process is killed and restarted, ensuring
  clean resource cleanup.
  - Recovery mechanism: Automatically recovers from broken module states without manual intervention.
  - Graceful fallback: When HMR cannot handle a change (e.g., medusa-config.ts, .env), the server restarts completely.


### Architecture
```mermaid
  flowchart TB
      subgraph Parent["develop.ts (File Watcher)"]
          W[Watch Files]
      end

      subgraph Child["start.ts (HTTP Server)"]
          R[reloadResources]
          R --> MR[ModuleReloader]
          R --> WR[WorkflowReloader]
          R --> RR[RouteReloader]
          R --> SR[SubscriberReloader]
          R --> JR[JobReloader]
      end

      W -->|"hmr-reload"| R
      R -->|"hmr-result"| W
```

### How to enable it

Backend HMR is behind a feature flag. Enable it by setting:

```ts
  // medusa-config.ts
  module.exports = defineConfig({
    featureFlags: {
      backend_hmr: true
    }
  })
```

or

```bash
export MEDUSA_FF_BACKEND_HMR=true
```

or

```
// .env
MEDUSA_FF_BACKEND_HMR=true
```

Co-authored-by: Oli Juhl <59018053+olivermrbl@users.noreply.github.com>
Co-authored-by: Carlos R. L. Rodrigues <37986729+carlos-r-l-rodrigues@users.noreply.github.com>

packages/core/utils/src/bundles.ts

@@ -19,3 +19,4 @@ export * as SearchUtils from "./search"
 export * as ShippingProfileUtils from "./shipping"
 export * as UserUtils from "./user"
 export * as CachingUtils from "./caching"
+export * as DevServerUtils from "./dev-server"

packages/core/utils/src/dev-server/handlers/job-handler.ts

@@ -0,0 +1,44 @@
+import { JobResourceData, ResourceEntry, ResourceTypeHandler } from "../types"
+
+export class JobHandler implements ResourceTypeHandler<JobResourceData> {
+  readonly type = "job"
+
+  validate(data: JobResourceData): void {
+    if (!data.id) {
+      throw new Error(
+        `Job registration requires id. Received: ${JSON.stringify(data)}`
+      )
+    }
+
+    if (!data.sourcePath) {
+      throw new Error(
+        `Job registration requires sourcePath. Received: ${JSON.stringify(
+          data
+        )}`
+      )
+    }
+
+    if (!data.config?.name) {
+      throw new Error(
+        `Job registration requires config.name. Received: ${JSON.stringify(
+          data
+        )}`
+      )
+    }
+  }
+
+  resolveSourcePath(data: JobResourceData): string {
+    return data.sourcePath
+  }
+
+  createEntry(data: JobResourceData): ResourceEntry {
+    return {
+      id: data.id,
+      config: data.config,
+    }
+  }
+
+  getInverseKey(data: JobResourceData): string {
+    return `${this.type}:${data.config?.name}`
+  }
+}

packages/core/utils/src/dev-server/handlers/step-handler.ts

@@ -0,0 +1,52 @@
+import { ResourceEntry, ResourceTypeHandler, StepResourceData } from "../types"
+
+export class StepHandler implements ResourceTypeHandler<StepResourceData> {
+  readonly type = "step"
+
+  constructor(private inverseRegistry: Map<string, string[]>) {}
+
+  validate(data: StepResourceData): void {
+    if (!data.id) {
+      throw new Error(
+        `Step registration requires id. Received: ${JSON.stringify(data)}`
+      )
+    }
+
+    if (!data.sourcePath && !data.workflowId) {
+      throw new Error(
+        `Step registration requires either sourcePath or workflowId. Received: ${JSON.stringify(
+          data
+        )}`
+      )
+    }
+  }
+
+  resolveSourcePath(data: StepResourceData): string {
+    if (data.sourcePath) {
+      return data.sourcePath
+    }
+
+    // Look up workflow's source path
+    const workflowKey = `workflow:${data.workflowId}`
+    const workflowSourcePaths = this.inverseRegistry.get(workflowKey)
+
+    if (!workflowSourcePaths || workflowSourcePaths.length === 0) {
+      throw new Error(
+        `step workflow not found: ${data.workflowId} for step ${data.id}`
+      )
+    }
+
+    return workflowSourcePaths[0]
+  }
+
+  createEntry(data: StepResourceData): ResourceEntry {
+    return {
+      id: data.id,
+      workflowId: data.workflowId,
+    }
+  }
+
+  getInverseKey(data: StepResourceData): string {
+    return `${this.type}:${data.id}`
+  }
+}

packages/core/utils/src/dev-server/handlers/subscriber-handler.ts

@@ -0,0 +1,67 @@
+import {
+  ResourceEntry,
+  ResourceTypeHandler,
+  SubscriberResourceData,
+} from "../types"
+
+export class SubscriberHandler
+  implements ResourceTypeHandler<SubscriberResourceData>
+{
+  readonly type = "subscriber"
+
+  validate(data: SubscriberResourceData): void {
+    if (!data.id) {
+      throw new Error(
+        `Subscriber registration requires id. Received: ${JSON.stringify(data)}`
+      )
+    }
+
+    if (!data.sourcePath) {
+      throw new Error(
+        `Subscriber registration requires sourcePath. Received: ${JSON.stringify(
+          data
+        )}`
+      )
+    }
+
+    if (!data.subscriberId) {
+      throw new Error(
+        `Subscriber registration requires subscriberId. Received: ${JSON.stringify(
+          data
+        )}`
+      )
+    }
+
+    if (!data.events) {
+      throw new Error(
+        `Subscriber registration requires events. Received: ${JSON.stringify(
+          data
+        )}`
+      )
+    }
+
+    if (!Array.isArray(data.events)) {
+      throw new Error(
+        `Subscriber registration requires events to be an array. Received: ${JSON.stringify(
+          data
+        )}`
+      )
+    }
+  }
+
+  resolveSourcePath(data: SubscriberResourceData): string {
+    return data.sourcePath
+  }
+
+  createEntry(data: SubscriberResourceData): ResourceEntry {
+    return {
+      id: data.id,
+      subscriberId: data.subscriberId,
+      events: data.events,
+    }
+  }
+
+  getInverseKey(data: SubscriberResourceData): string {
+    return `${this.type}:${data.subscriberId}`
+  }
+}

packages/core/utils/src/dev-server/handlers/workflow-handler.ts

@@ -0,0 +1,42 @@
+import {
+  ResourceEntry,
+  ResourceTypeHandler,
+  WorkflowResourceData,
+} from "../types"
+
+export class WorkflowHandler
+  implements ResourceTypeHandler<WorkflowResourceData>
+{
+  readonly type = "workflow"
+
+  validate(data: WorkflowResourceData): void {
+    if (!data.sourcePath) {
+      throw new Error(
+        `Workflow registration requires sourcePath. Received: ${JSON.stringify(
+          data
+        )}`
+      )
+    }
+
+    if (!data.id) {
+      throw new Error(
+        `Workflow registration requires id. Received: ${JSON.stringify(data)}`
+      )
+    }
+  }
+
+  resolveSourcePath(data: WorkflowResourceData): string {
+    return data.sourcePath
+  }
+
+  createEntry(data: WorkflowResourceData): ResourceEntry {
+    return {
+      id: data.id,
+      workflowId: data.id,
+    }
+  }
+
+  getInverseKey(data: WorkflowResourceData): string {
+    return `${this.type}:${data.id}`
+  }
+}

packages/core/utils/src/dev-server/index.ts

@@ -0,0 +1,154 @@
+import { FeatureFlag } from "../feature-flags"
+import { JobHandler } from "./handlers/job-handler"
+import { StepHandler } from "./handlers/step-handler"
+import { SubscriberHandler } from "./handlers/subscriber-handler"
+import { WorkflowHandler } from "./handlers/workflow-handler"
+import {
+  addToInverseRegistry,
+  addToRegistry,
+  getOrCreateRegistry,
+} from "./registry-helpers"
+import {
+  BaseResourceData,
+  ResourceMap,
+  ResourcePath,
+  ResourceRegistrationData,
+  ResourceTypeHandler,
+} from "./types"
+
+export type {
+  BaseResourceData,
+  ResourceEntry,
+  ResourceMap,
+  ResourcePath,
+  ResourceType,
+  ResourceTypeHandler,
+} from "./types"
+
+/**
+ * Maps source file paths to their registered resources
+ * Structure: sourcePath -> Map<resourceType, ResourceEntry[]>
+ */
+export const globalDevServerRegistry = new Map<ResourcePath, ResourceMap>()
+
+/**
+ * Inverse registry for looking up source paths by resource
+ * Structure: "type:id" -> sourcePath[]
+ * Used to find which files contain a specific resource
+ */
+export const inverseDevServerRegistry = new Map<ResourcePath, ResourcePath[]>()
+
+/**
+ * Registry of resource type handlers
+ * Each handler implements the logic for a specific resource type
+ */
+const resourceHandlers = new Map<string, ResourceTypeHandler>()
+
+/**
+ * Register a resource type handler
+ *
+ * @example
+ * ```typescript
+ * class RouteHandler implements ResourceTypeHandler<RouteData> {
+ *   readonly type = "route"
+ *   validate(data: RouteData): void { ... }
+ *   resolveSourcePath(data: RouteData): string { ... }
+ *   createEntry(data: RouteData): ResourceEntry { ... }
+ *   getInverseKey(data: RouteData): string { ... }
+ * }
+ *
+ * registerResourceTypeHandler(new RouteHandler())
+ * ```
+ */
+export function registerResourceTypeHandler(
+  handler: ResourceTypeHandler
+): void {
+  if (resourceHandlers.has(handler.type)) {
+    console.warn(
+      `Resource type handler for "${handler.type}" is being overridden`
+    )
+  }
+
+  resourceHandlers.set(handler.type, handler)
+}
+
+registerResourceTypeHandler(new WorkflowHandler())
+registerResourceTypeHandler(new StepHandler(inverseDevServerRegistry))
+registerResourceTypeHandler(new SubscriberHandler())
+registerResourceTypeHandler(new JobHandler())
+
+/**
+ * Register a resource in the dev server for hot module reloading
+ *
+ * This function uses a strategy pattern where each resource type has its own handler.
+ * The handler is responsible for:
+ * - Validating the registration data
+ * - Resolving the source path
+ * - Creating the registry entry
+ * - Generating the inverse registry key
+ *
+ * @param data - Resource registration data
+ * @throws Error if validation fails or handler is not found
+ *
+ * @example
+ * ```typescript
+ * // Register a workflow
+ * registerDevServerResource({
+ *   type: "workflow",
+ *   id: "create-product",
+ *   sourcePath: "/src/workflows/create-product.ts"
+ * })
+ *
+ * // Register a step
+ * registerDevServerResource({
+ *   type: "step",
+ *   id: "validate-product",
+ *   workflowId: "create-product"
+ * })
+ * ```
+ */
+export function registerDevServerResource(data: ResourceRegistrationData): void
+export function registerDevServerResource<T extends BaseResourceData>(
+  data: T
+): void
+export function registerDevServerResource<T extends BaseResourceData>(
+  data: T
+): void {
+  // Skip registration in production or if HMR is disabled
+  const isProduction = ["production", "prod"].includes(
+    process.env.NODE_ENV || ""
+  )
+
+  if (!FeatureFlag.isFeatureEnabled("backend_hmr") || isProduction) {
+    return
+  }
+
+  const handler = resourceHandlers.get(data.type)
+
+  if (!handler) {
+    throw new Error(
+      `No handler registered for resource type "${data.type}". ` +
+        `Available types: ${Array.from(resourceHandlers.keys()).join(", ")}. ` +
+        `Use registerResourceTypeHandler() to add support for custom types.`
+    )
+  }
+
+  try {
+    handler.validate(data)
+
+    const sourcePath = handler.resolveSourcePath(data)
+
+    const registry = getOrCreateRegistry(globalDevServerRegistry, sourcePath)
+
+    const entry = handler.createEntry(data)
+    addToRegistry(registry, data.type, entry)
+
+    const inverseKey = handler.getInverseKey(data)
+    addToInverseRegistry(inverseDevServerRegistry, inverseKey, sourcePath)
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error)
+    throw new Error(
+      `Failed to register ${data.type} resource "${data.id}": ${errorMessage}`
+    )
+  }
+}

packages/core/utils/src/dev-server/registry-helpers.ts

@@ -0,0 +1,34 @@
+import { ResourceEntry, ResourceMap, ResourcePath } from "./types"
+
+export function getOrCreateRegistry(
+  globalRegistry: Map<ResourcePath, ResourceMap>,
+  sourcePath: string
+): ResourceMap {
+  let registry = globalRegistry.get(sourcePath)
+
+  if (!registry) {
+    registry = new Map<string, ResourceEntry[]>()
+    globalRegistry.set(sourcePath, registry)
+  }
+
+  return registry
+}
+
+export function addToRegistry(
+  registry: ResourceMap,
+  type: string,
+  entry: ResourceEntry
+): void {
+  const entries = registry.get(type) || []
+  registry.set(type, [...entries, entry])
+}
+
+export function addToInverseRegistry(
+  inverseRegistry: Map<string, string[]>,
+  key: string,
+  sourcePath: string
+): void {
+  const existing = inverseRegistry.get(key) || []
+  const updated = Array.from(new Set([...existing, sourcePath]))
+  inverseRegistry.set(key, updated)
+}

packages/core/utils/src/dev-server/types.ts

@@ -0,0 +1,59 @@
+export type ResourcePath = string
+export type ResourceType = string
+export type ResourceEntry = {
+  id: string
+  workflowId?: string
+  [key: string]: any
+}
+export type ResourceMap = Map<string, ResourceEntry[]>
+
+export interface BaseResourceData {
+  type: string
+  id: string
+  sourcePath?: string
+}
+
+export interface WorkflowResourceData extends BaseResourceData {
+  type: "workflow"
+  sourcePath: string
+}
+
+export interface StepResourceData extends BaseResourceData {
+  type: "step"
+  workflowId?: string
+  sourcePath?: string
+}
+
+export interface SubscriberResourceData extends BaseResourceData {
+  type: "subscriber"
+  sourcePath: string
+  subscriberId: string
+  events: string[]
+}
+
+export interface JobResourceData extends BaseResourceData {
+  type: "job"
+  sourcePath: string
+  config: {
+    name: string
+  }
+}
+
+export type ResourceRegistrationData =
+  | WorkflowResourceData
+  | StepResourceData
+  | SubscriberResourceData
+
+export interface ResourceTypeHandler<
+  T extends BaseResourceData = BaseResourceData
+> {
+  readonly type: string
+
+  validate(data: T): void
+
+  resolveSourcePath(data: T): string
+
+  createEntry(data: T): ResourceEntry
+
+  getInverseKey(data: T): string
+}

packages/core/utils/src/index.ts

@@ -30,6 +30,7 @@ export * from "./totals"
 export * from "./totals/big-number"
 export * from "./user"
 export * from "./caching"
+export * from "./dev-server"
 
 export const MedusaModuleType = Symbol.for("MedusaModule")
 export const MedusaModuleProviderType = Symbol.for("MedusaModuleProvider")