Skip to main content

Nexus Patterns

SUPPORT, STABILITY, and DEPENDENCY INFO

Temporal Nexus is now Generally Available for Temporal Cloud and self-hosted deployments.

There are two common patterns for building and deploying Nexus Services:

  • Collocated pattern: Runs on the same Workers as your existing Workflows and Activities. Use by default.
  • Router pattern: Separates Nexus routing from Workflow execution. A dedicated Nexus Worker on a “router” Task Queue routes Operations to Workflows on other Task Queues. Use when you need independent scaling, different IAM permissions per Worker fleet, or want to add Nexus to without modifying existing Workers.

Collocated pattern (default)​

The collocated pattern runs Nexus Operation handlers in the same Worker and on the same Task Queue as the underlying Workflows. This is the default and simplest deployment.

The Nexus Endpoint targets the same Task Queue used by the underlying Workflows. A single Worker registers both Nexus Services and Workflow types, so everything runs together.

Why start here​

  • Simplest setup: One Worker, one Task Queue, one deployment. No extra infrastructure.
  • Eager Workflow Start: When the handler starts a Workflow in the same Worker, you can use Eager Workflow Start to execute the first Workflow Task locally without an extra call to the Temporal Server - while still recording durable state. If the process crashes, the Workflow resumes on another Worker.
  • Clean facade: Operations act as a stable contract. You can change the underlying implementation (Signal today, Workflow tomorrow) without impacting callers.

When to use this pattern​

  • Getting started with Nexus.
  • The same team owns both the Nexus Service and underlying Workflows.
  • You don't need to scale Nexus routing separately from Workflow execution.
  • You are setting up a simple test environment

Use this pattern by default unless you have a good reason to use the Router-queue pattern below

Router-queue pattern​

The router-queue pattern separates Nexus routing from Workflow execution. A dedicated Nexus Worker on a "router" Task Queue routes Operations to Workflows on other Task Queues in the same Namespace.

When to use this pattern​

  • Separate scaling: Scale Nexus routing independently from Workflow execution.
  • Dedicated routing layer: A single Nexus Worker routes requests to multiple Workflow types on different Task Queues.
  • Different IAM permissions: Worker fleets behind different Task Queues may have different IAM permissions to different underlying resources.
  • Avoid modifying existing Workers: Add a router Worker to a Namespace without changing any existing Workers or Workflows.

How it works​

  1. Register a Nexus Worker that polls a dedicated "router" Task Queue.
  2. Configure the Nexus Endpoint's target Task Queue to point to this router Task Queue.
  3. In each Nexus Operation handler, specify a different target Task Queue in the Workflow start options.
  4. Existing Workers continue to poll their own Task Queues and execute the Workflows started by the router.

Production usage​

Used in production by organizations running self-service platforms where a central gateway routes requests to domain-specific Namespaces and Task Queues. The router Worker is lightweight - it only handles routing logic.