Temporal Ts Nexus

• Local dev server (temporal server start-dev on localhost:7233)?
• Self-hosted cluster? If so, what is the full gRPC address (e.g. temporal.internal:7233)?
• Temporal Cloud? If so, what is the Cloud namespace address (e.g. <namespace>.<accountId>.tmprl.cloud:7233)?

These answers determine connection config, mTLS requirements, and CLI commands used below.

Overview

Temporal Nexus connects Temporal Applications within and across Namespaces using three primitives:

Status: Pre-release. All APIs are experimental and may have backwards-incompatible changes.

Key packages:

• nexus-rpc -- service/operation definitions, serviceHandler, error classes
• @temporalio/nexus -- WorkflowRunOperationHandler, startWorkflow, getClient
• @temporalio/workflow -- createNexusClient (caller side)
• @temporalio/worker -- nexusServices option on Worker.create

Quick Reference

Implementation Patterns

1. Define the Service Contract (shared between caller and handler)

// src/api.ts
import * as nexus from 'nexus-rpc';

export const myService = nexus.service('my-service', {
  echo: nexus.operation<EchoInput, EchoOutput>(),
  processOrder: nexus.operation<OrderInput, OrderOutput>(),
});

export interface EchoInput { message: string; }
export interface EchoOutput { message: string; }
export interface OrderInput { orderId: string; items: string[]; }
export interface OrderOutput { status: string; }

Inputs and outputs are plain TypeScript objects serialized as JSON by default. For Protobuf, use ProtobufJsonPayloadConverter.

2. Synchronous Operation Handler

Use for short-lived computations, queries, signals, or calls to external services.

// src/handler.ts
import * as nexus from 'nexus-rpc';
import * as temporalNexus from '@temporalio/nexus';
import { myService, EchoInput, EchoOutput } from './api';

export const myServiceHandler = nexus.serviceHandler(myService, {
  echo: async (ctx, input: EchoInput): Promise<EchoOutput> => {
    // Can also use temporalNexus.getClient() to query/signal workflows
    return { message: input.message };
  },
  // ... other operations
});

3. Asynchronous Operation Handler (Workflow-backed)

Use when the operation is long-running and should be backed by a durable Workflow.

// src/handler.ts
import { randomUUID } from 'crypto';
import * as nexus from 'nexus-rpc';
import * as temporalNexus from '@temporalio/nexus';
import { myService, OrderInput, OrderOutput } from './api';
import { processOrderWorkflow } from './workflows';

export const myServiceHandler = nexus.serviceHandler(myService, {
  // ...sync handlers...
  processOrder: new temporalNexus.WorkflowRunOperationHandler<OrderInput, OrderOutput>(
    async (ctx, input: OrderInput) => {
      return await temporalNexus.startWorkflow(ctx, processOrderWorkflow, {
        args: [input],
        // Use ctx.requestId for deduplication (stable across retries)
        workflowId: input.orderId ?? ctx.requestId ?? randomUUID(),
        // taskQueue defaults to the handler's task queue
      });
    },
  ),
});

Key points:

• ctx.requestId is stable across retries -- use it for deduplication when no business ID exists.
• Nexus operations accept only one input parameter. Pass multiple values as properties of the input object, then spread into the args array for the workflow.
• workflowId should be a business-meaningful ID when possible.

4. Register Handler in a Worker

// src/handler-worker.ts
import { Worker, NativeConnection } from '@temporalio/worker';
import { myServiceHandler } from './handler';

async function run() {
  const connection = await NativeConnection.connect({ address: 'localhost:7233' });
  const worker = await Worker.create({
    connection,
    namespace: 'my-target-namespace',
    taskQueue: 'my-handler-task-queue',
    workflowsPath: require.resolve('./workflows'),
    nexusServices: [myServiceHandler],  // <-- register here
  });
  await worker.run();
}

run().catch(console.error);

5. Caller Workflow

// src/caller-workflows.ts
import * as wf from '@temporalio/workflow';
import { myService } from './api';

const ENDPOINT_NAME = 'my-nexus-endpoint-name';

export async function callerWorkflow(orderId: string, items: string[]): Promise<string> {
  const nexusClient = wf.createNexusClient({
    service: myService,
    endpoint: ENDPOINT_NAME,
  });

  const result = await nexusClient.executeOperation(
    'processOrder',
    { orderId, items },
    { scheduleToCloseTimeout: '30s' }
  );

  return result.status;
}

6. Caller Worker and Starter

// src/caller-worker.ts
import { Worker, NativeConnection } from '@temporalio/worker';

async function run() {
  const connection = await NativeConnection.connect({ address: 'localhost:7233' });
  const worker = await Worker.create({
    connection,
    namespace: 'my-caller-namespace',
    taskQueue: 'my-caller-task-queue',
    workflowsPath: require.resolve('./caller-workflows'),
  });
  await worker.run();
}

run().catch(console.error);

// src/starter.ts
import { Client, Connection } from '@temporalio/client';

async function run() {
  const connection = await Connection.connect({ address: 'localhost:7233' });
  const client = new Client({ connection, namespace: 'my-caller-namespace' });

  const result = await client.workflow.execute('callerWorkflow', {
    taskQueue: 'my-caller-task-queue',
    workflowId: 'caller-1',
    args: ['order-123', ['item-a', 'item-b']],
  });

  console.log('Result:', result);
}

run().catch(console.error);

Infrastructure Setup

Local Development

# Start dev server
temporal server start-dev

# Create namespaces
temporal operator namespace create --namespace my-target-namespace
temporal operator namespace create --namespace my-caller-namespace

# Create Nexus endpoint
temporal operator nexus endpoint create \
  --name my-nexus-endpoint-name \
  --target-namespace my-target-namespace \
  --target-task-queue my-handler-task-queue

Temporal Cloud

# Install tcld
brew install temporalio/brew/tcld

# Generate certs (if needed)
tcld gen ca --org $YOUR_ORG --validity-period 1y --ca-cert ca.pem --ca-key ca.key

# Login
tcld login

# Create namespaces (if needed)
tcld namespace create \
  --namespace <caller-ns> \
  --cloud-provider aws --region us-west-2 \
  --ca-certificate-file ca.pem --retention-days 1

tcld namespace create \
  --namespace <target-ns> \
  --cloud-provider aws --region us-west-2 \
  --ca-certificate-file ca.pem --retention-days 1

# Create endpoint with allowlist
tcld nexus endpoint create \
  --name my-nexus-endpoint-name \
  --target-namespace <target-ns.account> \
  --target-task-queue my-handler-task-queue \
  --allow-namespace <caller-ns.account>

On Cloud, use --allow-namespace to control which caller Namespaces can use the endpoint.

Error Handling

HandlerErrorType retryability:

• Non-retryable: BAD_REQUEST, UNAUTHENTICATED, UNAUTHORIZED, NOT_FOUND, NOT_IMPLEMENTED
• Retryable: RESOURCE_EXHAUSTED, INTERNAL, UNAVAILABLE, UPSTREAM_TIMEOUT

import { OperationError, HandlerError } from 'nexus-rpc';

// In a handler:
throw new OperationError('Order not found');  // non-retryable app error
throw new HandlerError('Service overloaded', 'RESOURCE_EXHAUSTED');  // retryable

// In a caller workflow:
import { NexusOperationFailure } from '@temporalio/common';
try {
  await nexusClient.executeOperation('processOrder', input, opts);
} catch (err) {
  if (err instanceof NexusOperationFailure) {
    console.error('Nexus op failed:', err.cause);
  }
}

Cancellation

• Nexus Operations run inside Cancellation Scopes (same as Activities, Child Workflows).
• Cancelling the caller Workflow propagates cancellation to all its Nexus Operations.
• Only asynchronous operations can be cancelled (they have an operation token).
• The handler Workflow may choose to ignore the cancellation request.
• After the caller Workflow completes, no further cancellation attempts are made for still-running operations.

For granular cancellation, wrap the operation in an explicit CancellationScope:

import { CancellationScope } from '@temporalio/workflow';

const scope = new CancellationScope();
const handle = scope.run(() =>
  nexusClient.executeOperation('longRunning', input, opts)
);
// Later:
scope.cancel();

See the nexus-cancellation sample for a complete example.

Observability

Workflow history events (caller side):

CLI commands:

• temporal workflow describe -w <ID> -- shows pending Nexus operations and callbacks
• temporal workflow show -w <ID> -- shows full event history including Nexus events

Common Mistakes

1. Forgetting to create the Nexus Endpoint before starting the caller Workflow. The endpoint must exist and point to the correct target namespace and task queue.
2. Mismatched endpoint name between CLI creation and createNexusClient({ endpoint }) in the caller Workflow.
3. Mismatched task queue between endpoint creation (--target-task-queue) and Worker.create({ taskQueue }) in the handler.
4. Not registering nexusServices in the handler Worker -- the Worker will not pick up Nexus requests without it.
5. Using multiple positional args instead of a single input object. Nexus operations accept exactly one input parameter.
6. Missing scheduleToCloseTimeout on executeOperation -- this is required.
7. Trying to cancel a synchronous operation -- only async (Workflow-backed) operations support cancellation.
8. Not setting --allow-namespace on Temporal Cloud -- the caller namespace must be in the endpoint's allowlist.
9. Using pip install instead of uv pip install if your project also has Python components.

Debugging Tips

1. Check the Web UI at http://localhost:8233 (or your ingress URL) for Nexus endpoint configuration and Workflow history events.
2. Use temporal workflow show -w <ID> on both caller and handler Workflows to trace the full Nexus call chain.
3. Check Worker logs on both caller and handler sides. Connection errors, namespace mismatches, and task queue mismatches surface here.
4. Verify endpoint exists: temporal operator nexus endpoint list (local) or check Cloud UI at https://cloud.temporal.io/nexus.
5. Test the handler independently by starting the handler Workflow directly (without Nexus) to isolate whether the issue is in the Nexus plumbing or the Workflow logic.
6. Inspect NexusOperationFailure.cause in the caller Workflow for the root cause of handler failures.
7. For Cloud deployments, ensure mTLS certs are valid and that both Workers connect to the correct namespace addresses.

Additional Resources

If this skill does not answer your question, use Context7 to search /temporalio/sdk-typescript or /temporalio/samples-typescript for more details.

• TypeScript Nexus sample (nexus-hello)
• Nexus cancellation sample
• Temporal Nexus overview
• Nexus deep dive talk
• Temporal Cloud Nexus docs