Updated for Nexus SDK Ergonomics - Not ready to be merged yet!! - #5203
Open
Evanthx wants to merge 11 commits into
Open
Updated for Nexus SDK Ergonomics - Not ready to be merged yet!!#5203Evanthx wants to merge 11 commits into
Evanthx wants to merge 11 commits into
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
📖 Docs PR preview links
|
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
The Java guide duplicates existing documentation, lacks a runnable generated-contract setup, and leaves related Nexus pages inconsistent.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
Adds prerelease Nexus SDK ergonomics documentation and a Java implementation guide.
Changes:
- Documents the unified Temporal Operation Handler, code generation, and Activity-backed Operations.
- Adds a Java prerelease developer guide.
- Adds the new pages to Nexus navigation.
File summaries
| File | Description |
|---|---|
sidebars.js |
Registers and groups the new pages. |
docs/encyclopedia/nexus/temporal-operation-handler.mdx |
Explains the unified handler API. |
docs/encyclopedia/nexus/nexus-standalone-activity.mdx |
Describes Activity-backed Operations. |
docs/encyclopedia/nexus/nexus-code-generator.mdx |
Introduces generated Nexus contracts. |
docs/develop/java/nexus/developer-experience.mdx |
Provides Java usage and deployment guidance. |
Review details
- Files reviewed: 5/5 changed files
- Comments generated: 4
- Review effort level: Balanced
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| APIs are experimental and may be subject to backwards-incompatible changes. | ||
| </ReleaseNoteHeader> | ||
|
|
||
| Temporal has unified the Workflow handler and the synchronous operation handler into a single handler, and added the ability to back an Operation with a [Standalone Activity](/nexus/standalone-activity). |
Comment on lines
+19
to
+20
| The Nexus Code Generator, [`nexgen`](https://github.com/temporalio/nex-gen), turns one schema into client code for Go, Java, Python, and TypeScript. | ||
| Both sides of a [Nexus Service](/nexus/services) generate from the same file, so neither hand-writes the types and neither can drift from the contract. |
Comment on lines
+95
to
+97
| You can hand-write that package, but the preferred way is to generate it with the [Nexus Code Generator](https://github.com/temporalio/nex-gen). | ||
| You write the contract once as a JSON definition file and run `nexgen` against it, and it emits the typed models, | ||
| runtime validators, and the Service definition itself. |
Contributor
|
Taking a quick look at this. Will do a deeper look this week. |
jsundai
reviewed
Sep 2, 2026
jsundai
reviewed
Sep 2, 2026
|
|
jsundai
reviewed
Sep 2, 2026
jsundai
reviewed
Sep 2, 2026
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
The new guides duplicate existing feature guides, omit collateral updates, and incorrectly claim .NET code-generation support.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Review details
Suppressed comments (2)
docs/develop/java/nexus/developer-experience.mdx:4
- This creates a second full Nexus feature guide beside
docs/develop/java/nexus/feature-guide.mdx; 602 of this page's 696 lines duplicate that guide. The documented SDK structure defines Nexus as a Quickstart plus one feature guide (readme/INFORMATION-ARCHITECTURE.md:150-151). Merge the ergonomics updates into the existing feature guide instead of publishing parallel guides that can drift.
title: Nexus Developer Experience - Java SDK feature guide
docs/encyclopedia/nexus/temporal-operation-handler.mdx:19
- The parent and lifecycle pages still describe the old handler model:
docs/encyclopedia/nexus/nexus.mdx:50-55says asynchronous Operations only start Workflows and treats Updates as synchronous, whiledocs/encyclopedia/nexus/nexus-operations.mdx:16,36-39still documents Workflow-backed async and separateNew-Workflow-Run-Operation/New-Sync-Operationbuilders. Update those pages alongside this unified handler so readers do not get conflicting definitions of async backings and handler APIs.
Temporal has unified the Workflow handler and the synchronous operation handler into a single handler, and added the ability to back an Operation with a [Standalone Activity](/nexus/standalone-activity).
- Files reviewed: 9/9 changed files
- Comments generated: 5
- Review effort level: Balanced
Comment on lines
+96
to
+110
| You can hand-write that package, but the preferred way is to generate it with the [Nexus Code Generator](https://github.com/temporalio/nex-gen). | ||
| You write the contract once as a JSON definition file and run `nexgen` against it, and it emits the typed models, | ||
| runtime validators, and the Service definition itself. | ||
|
|
||
| This is what makes a Nexus Service polyglot. Both sides generate from the same definition file: the handler implements | ||
| the Service, the caller invokes its Operations, and neither hand-writes a request or response type. A Python handler | ||
| and a Go caller share no code, but they both run off that same service contract - so they interoperate with no | ||
| coordination between the teams beyond the contract itself. | ||
|
|
||
| The generated validators check every payload against the contract, when a value is parsed off the wire and again when | ||
| it is serialized onto it, so bad data is rejected at the boundary rather than reaching your Workflow. A value validates | ||
| identically in every language, which is what lets a caller and a handler written in different languages trust the same | ||
| contract. See the [`chat.nexusrpc.yaml`](https://github.com/temporalio/nex-gen/blob/main/samples/schemas/chat.nexusrpc.yaml) | ||
| sample contract and the [Definition files](https://github.com/temporalio/nex-gen#definition-files) section of the | ||
| `nexgen` README for the file format. |
| --- | ||
| id: developer-experience | ||
| slug: /develop/dotnet/nexus/developer-experience | ||
| title: Nexus Developer Experience - .NET SDK feature guide |
| --- | ||
| id: developer-experience | ||
| slug: /develop/go/nexus/developer-experience | ||
| title: Nexus Developer Experience - Go SDK feature guide |
| --- | ||
| id: developer-experience | ||
| slug: /develop/python/nexus/developer-experience | ||
| title: Nexus Developer Experience - Python SDK feature guide |
| --- | ||
| id: developer-experience | ||
| slug: /develop/typescript/nexus/developer-experience | ||
| title: Nexus Developer Experience - TypeScript SDK feature guide |
Contributor
✅ Docs build passed |
Contributor
|
Let's keep the feature guide as the title for now. The content of the dev experience page should all still be there since it's folded into the page but we can keep the feature page metadata - this also avoids changing all the redirects/urls. I added a callout that there's a new developer experience. Going to make a few more edits. |
bergundy
reviewed
Sep 5, 2026
bergundy
left a comment
bergundy
left a comment
Member
There was a problem hiding this comment.
I started reviewing the whole guide and stopped myself. I am debating whether to spend time on that or not. The nexgen docs were fully reviewed.
|
|
||
| :::note | ||
|
|
||
| This Feature Guide includes the new Nexus developer experience: pre-release APIs for the [Temporal Operation Handler](/nexus/temporal-operation-handler) and [Nexus Standalone Activity](/nexus/standalone-activity). These APIs are experimental and may change. |
Member
There was a problem hiding this comment.
I don't think we should call this feature "Nexus standalone activity", but you can say that this guide covers invoking a standalone activity from a nexus handler.
Member
There was a problem hiding this comment.
nit: I would say "subject to change".
| Handlers should be reliable since the [circuit breaker](/nexus/operations#circuit-breaking) trips after 5 consecutive retryable errors, blocking all Operations from the caller to that Endpoint. | ||
|
|
||
| The `Temporalio.Nexus` namespace has utilities to help create Nexus Operations: | ||
| Every Operation is written with [`TemporalOperationHandler`](/nexus/temporal-operation-handler). Mark a method |
Member
There was a problem hiding this comment.
I feel like this statement is confusing. We don't show the TemporalOperationHandler just the shorthand TemporalOperation.
Comment on lines
+4
to
+5
| sidebar_label: Nexus Code Generator | ||
| description: The Nexus Code Generator turns one schema into typed models, runtime validators, and Nexus Service definitions for Go, Java, Python, and TypeScript. |
Member
There was a problem hiding this comment.
Can we call this nexgen to match the language everywhere?
Same goes for the name of the file.
Contributor
|
Making a few more edits and doing final review today. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This adds and updates some information about Nexus SDK ergonomics.
Dev Experience page replaces the Nexus feature guide.