fix(tanstack-react-query): add prefix support for mutation options by tmkx · Pull Request #7370 · trpc/trpc

tmkx · 2026-05-04T16:33:51Z

🎯 Changes

Add prefix parameter to mutation options to support key prefixing from proxy/context level. This allows mutation key prefixes to be defined at a higher level while still allowing per-mutation overrides.

✅ Checklist

I have followed the steps listed in the Contributing guide.
If necessary, I have added documentation related to the changes made.
I have added or updated the tests related to the changes made.

Summary by CodeRabbit

Bug Fixes
- Fixed mutation key generation to properly use key-prefixing context from the proxy, ensuring mutations are keyed consistently even when no explicit prefix is provided.
Tests
- Added test coverage for mutation key generation with proxy key-prefixing defaults.

Add prefix parameter to mutation options to support key prefixing from proxy/context level. This allows mutation key prefixes to be defined at a higher level while still allowing per-mutation overrides.

vercel · 2026-05-04T16:33:58Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
next-prisma-starter	Error		May 4, 2026 4:34pm
og-image	Ready	Preview, Comment	May 4, 2026 4:34pm

coderabbitai · 2026-05-04T16:34:07Z

📝 Walkthrough

Walkthrough

This PR fixes a bug where mutationOptions().mutationKey was missing the configured key prefix context. The fix threads the proxy's prefix value into the mutation options generator and uses it as a fallback when individual option overrides don't specify their own keyPrefix.

Changes

Key Prefix Threading

Layer / File(s)	Summary
Type & Logic Updates `packages/tanstack-react-query/src/internals/mutationOptions.ts`	`trpcMutationOptions` now accepts `prefix: string \| undefined` parameter; `mutationKey` derivation updated to use `opts?.keyPrefix ?? prefix` instead of only `opts?.keyPrefix`.
Integration Wiring `packages/tanstack-react-query/src/internals/createOptionsProxy.ts`	The `mutationOptions` generator now passes the proxy's `prefix` value into `trpcMutationOptions(...)` call.
Tests & Verification `packages/tanstack-react-query/test/mutationOptions.test.tsx`	New test case verifies that mutation defaults registered via proxied keyPrefix are applied even when `opts.keyPrefix` is omitted.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

fix(tanstack-react-query): keyPrefix of undefined #6990: Also modifies keyPrefix handling in trpcMutationOptions to support optional opts and optional chaining for keyPrefix resolution.
feat(tanstack-react-query): Add QueryKey and MutationKey Prefix option #6976: Extends mutation key prefixing behavior through changes to both createOptionsProxy and mutationOptions modules.

Suggested reviewers

KATT
Nick-Lucas

Poem

🐰 A prefix went missing, oh what a shame!
The mutation key lost its proper name,
But now with a thread through the proxy's core,
The keyPrefix flows where it flowed before! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the primary change: adding prefix support to mutation options in the tanstack-react-query integration, which directly addresses the bug described in the linked issue.
Description check	✅ Passed	The description includes the issue reference, a clear explanation of changes, and covers the checklist items. However, the documentation update is not yet completed as noted in the checklist.
Linked Issues check	✅ Passed	The PR successfully addresses issue `#7369` by implementing the prefix parameter in mutation options, ensuring mutationKey includes keyPrefix from proxy/context level, and adds tests to verify the behavior.
Out of Scope Changes check	✅ Passed	All changes are scoped to the stated objective: updating mutation options to support prefix parameter in three files with coordinated changes and corresponding tests.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

Generate code and open pull requests
Plan features and break down work
Investigate incidents and troubleshoot customer tickets together
Automate recurring tasks and respond to alerts with triggers
Summarize progress and report instantly

Built for teams:

Shared memory across your entire org—no repeating context
Per-thread sandboxes to safely plan and execute work
Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Review rate limit: 7/8 reviews remaining, refill in 7 minutes and 30 seconds.}

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

🧹 Nitpick comments (1)

packages/tanstack-react-query/src/internals/mutationOptions.ts (1)
111-114: Runtime fix is correct; the call site's static type for mutationKey remains inconsistent with mutationKey()

The opts?.keyPrefix ?? prefix fallback correctly aligns the runtime mutationKey value with what mutationKey() produces. However, DecorateMutationProcedure<TDef> declares:
mutationOptions: TRPCMutationOptions<TDef>; // TFeatureFlags defaults to DefaultFeatureFlags
mutationKey: () => TRPCMutationKey<TDef['featureFlags']['keyPrefix']>;
Because the second generic of TRPCMutationOptions defaults to DefaultFeatureFlags rather than TDef['featureFlags'], the TypeScript type of mutationOptions().mutationKey is TRPCMutationKey<DefaultFeatureFlags['keyPrefix']>, not TRPCMutationKey<TDef['featureFlags']['keyPrefix']>. This means consumers with a prefix-enabled proxy see a less-precise type from mutationOptions() than from mutationKey(), even though the runtime values are now identical.

The fix is a one-line change in createOptionsProxy.ts, DecorateMutationProcedure<TDef>:
♻️ Proposed type fix
-  mutationOptions: TRPCMutationOptions<TDef>;
+  mutationOptions: TRPCMutationOptions<TDef, TDef['featureFlags']>;
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@packages/tanstack-react-query/src/internals/mutationOptions.ts` around lines
111 - 114, DecorateMutationProcedure<TDef>'s mutationOptions type uses
TRPCMutationOptions with the default feature flags, causing
mutationOptions().mutationKey to be typed with DefaultFeatureFlags; update the
declaration in createOptionsProxy.ts so mutationOptions passes
TDef['featureFlags'] as the second generic (e.g. change mutationOptions:
TRPCMutationOptions<TDef> to mutationOptions: TRPCMutationOptions<TDef,
TDef['featureFlags']>) so its mutationKey type matches the existing
mutationKey(): TRPCMutationKey<TDef['featureFlags']['keyPrefix']>.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@packages/tanstack-react-query/src/internals/mutationOptions.ts`:
- Around line 111-114: DecorateMutationProcedure<TDef>'s mutationOptions type
uses TRPCMutationOptions with the default feature flags, causing
mutationOptions().mutationKey to be typed with DefaultFeatureFlags; update the
declaration in createOptionsProxy.ts so mutationOptions passes
TDef['featureFlags'] as the second generic (e.g. change mutationOptions:
TRPCMutationOptions<TDef> to mutationOptions: TRPCMutationOptions<TDef,
TDef['featureFlags']>) so its mutationKey type matches the existing
mutationKey(): TRPCMutationKey<TDef['featureFlags']['keyPrefix']>.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: d87ae420-4ba9-43ae-9b79-418798be8697

📥 Commits

Reviewing files that changed from the base of the PR and between 23c723c and 7e30fde.

📒 Files selected for processing (3)

packages/tanstack-react-query/src/internals/createOptionsProxy.ts
packages/tanstack-react-query/src/internals/mutationOptions.ts
packages/tanstack-react-query/test/mutationOptions.test.tsx

fix(tanstack-react-query): add prefix support for mutation options

7e30fde

Add prefix parameter to mutation options to support key prefixing from proxy/context level. This allows mutation key prefixes to be defined at a higher level while still allowing per-mutation overrides.

tmkx requested a review from a team as a code owner May 4, 2026 16:33

vercel Bot had a problem deploying to Preview – next-prisma-starter May 4, 2026 16:34 Failure

vercel Bot had a problem deploying to Preview – trpc-next-app-dir May 4, 2026 16:34 Failure

vercel Bot deployed to Preview – og-image May 4, 2026 16:34 View deployment

vercel Bot deployed to Preview – examples-todomvc May 4, 2026 16:35 View deployment

vercel Bot had a problem deploying to Preview – www May 4, 2026 16:35 Failure

coderabbitai Bot reviewed May 4, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix(tanstack-react-query): add prefix support for mutation options#7370

fix(tanstack-react-query): add prefix support for mutation options#7370
tmkx wants to merge 1 commit into
trpc:mainfrom
tmkx:fix/query-mutation-key-prefix

tmkx commented May 4, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

vercel Bot commented May 4, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented May 4, 2026 •

edited

Loading

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Suggested reviewers

Poem

❌ Failed checks (1 warning)

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

tmkx commented May 4, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🎯 Changes

✅ Checklist

Summary by CodeRabbit

Uh oh!

vercel Bot commented May 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai Bot commented May 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Suggested reviewers

Poem

❌ Failed checks (1 warning)

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

tmkx commented May 4, 2026 •

edited by coderabbitai Bot

Loading

vercel Bot commented May 4, 2026 •

edited

Loading

coderabbitai Bot commented May 4, 2026 •

edited

Loading