[feat]: Add stable IDs for server functions

[LadyBluenotes]

Summary by CodeRabbit

• New Features
  • Added optional support for manually providing a custom id when creating server functions for stable identifier-based runtime lookup, including through chaining and locally named re-exports.
• Bug Fixes
  • Improved server-function ID reservation, deduping, and lifecycle across recompilations (including HMR) to prevent stale/duplicate IDs.
  • Detects and rejects computed or non-statically analyzable id shapes, and enforces collision rules for manual/manual and manual/generated cases.
• Documentation
  • Added a guide for manual server function IDs, including collision behavior and security caveats.
• Tests
  • Expanded type-level and compiler/runtime coverage for manual IDs, collisions, and invalidation/reuse behavior.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

This PR adds optional id support to createServerFn and threads explicit server-function IDs through compiler reservation, invalidation cleanup, docs, and tests.

Changes

Manual server-function ID reservation

Layer / File(s)	Summary
Public id option surface packages/start-client-core/src/createServerFn.ts, packages/start-client-core/src/tests/createServerFn.test-d.ts, packages/start-plugin-core/src/start-compiler/types.ts	createServerFn option types gain optional id?: string, CompilationContext gains reserveFunctionId, and the type test asserts a createServerFn({ id }) call exposes handler.
Compiler reservation lifecycle packages/start-plugin-core/src/start-compiler/compiler.ts	StartCompiler tracks reserved manual IDs, updates ID generation and deduplication, clears reservations on module invalidation, and exposes the new context handler.
Manual id extraction and handler wiring packages/start-plugin-core/src/start-compiler/handleCreateServerFn.ts	handleCreateServerFn extracts static id options, validates the format, and reserves explicit IDs when present.
ID behavior tests and docs packages/start-plugin-core/tests/createServerFn/createServerFn.test.ts, docs/start/framework/react/guide/server-functions.md	The plugin tests cover manual ID extraction, unsupported computed keys, generated ID collisions, reserved-ID reuse and release, dev-mode encoding, and the docs describe manual server-function IDs and collision rules.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Poem

🐰 I hopped through IDs and found a name,
createServerFn now plays the same.
Reserved and checked, then set in place,
HMR can clear its little trace.
I nibble tests and carrots with glee! 🥕

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% 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
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: adding stable/manual IDs for server functions.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch stable-serverfn-ids-2

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[nx-cloud]

View your CI Pipeline Execution ↗ for commit e58444b

Command	Status	Duration	Result
nx affected --targets=test:eslint,test:unit,tes...	❌ Failed	21m 48s	View ↗
nx run-many --target=build --exclude=examples/*...	✅ Succeeded	51s	View ↗

---

☁️ Nx Cloud last updated this comment at 2026-07-12 19:49:52 UTC

[github-actions]

🚀 Changeset Version Preview

2 package(s) bumped directly, 12 bumped as dependents.

🟨 Minor bumps

Package	Version	Reason
@tanstack/start-client-core	1.170.13 → 1.171.0	Changeset
@tanstack/start-plugin-core	1.171.19 → 1.172.0	Changeset

🟩 Patch bumps

Package	Version	Reason
@tanstack/react-start	1.168.27 → 1.168.28	Dependent
@tanstack/react-start-client	1.168.15 → 1.168.16	Dependent
@tanstack/react-start-rsc	0.1.26 → 0.1.27	Dependent
@tanstack/react-start-server	1.167.21 → 1.167.22	Dependent
@tanstack/solid-start	1.168.27 → 1.168.28	Dependent
@tanstack/solid-start-client	1.168.15 → 1.168.16	Dependent
@tanstack/solid-start-server	1.167.21 → 1.167.22	Dependent
@tanstack/start-server-core	1.169.16 → 1.169.17	Dependent
@tanstack/start-static-server-functions	1.167.18 → 1.167.19	Dependent
@tanstack/vue-start	1.168.26 → 1.168.27	Dependent
@tanstack/vue-start-client	1.167.18 → 1.167.19	Dependent
@tanstack/vue-start-server	1.167.21 → 1.167.22	Dependent

[github-actions]

Bundle Size Benchmarks

• Commit: f213c1aa564d
• Measured at: 2026-07-12T19:29:10.808Z
• Baseline source: history:a3e24c35a58d
• Dashboard: bundle-size history

Scenario	Current (gzip)	Delta vs baseline	Initial gzip	Raw	Brotli	Trend
react-router.minimal	87.37 KiB	0 B (0.00%)	87.24 KiB	273.88 KiB	75.99 KiB	▁▄▄▄▄██████
react-router.full	91.10 KiB	0 B (0.00%)	90.96 KiB	285.78 KiB	79.15 KiB	▁▅▅▅▅██████
solid-router.minimal	35.56 KiB	0 B (0.00%)	35.44 KiB	106.08 KiB	32.05 KiB	▁▅▅▅▅██████
solid-router.full	40.61 KiB	0 B (0.00%)	40.49 KiB	121.30 KiB	36.54 KiB	▁▆▆▆▆██████
vue-router.minimal	53.07 KiB	0 B (0.00%)	52.94 KiB	150.12 KiB	47.70 KiB	▁▄▄▄▄██████
vue-router.full	59.03 KiB	0 B (0.00%)	58.90 KiB	168.88 KiB	52.93 KiB	▁▄▄▄▄██████
react-start.minimal	102.03 KiB	0 B (0.00%)	101.89 KiB	322.31 KiB	88.32 KiB	▁▃▃▃▆██████
react-start.deferred-hydration	102.76 KiB	0 B (0.00%)	101.91 KiB	323.69 KiB	88.91 KiB	▁▄▄▄▆██████
react-start.full	105.45 KiB	0 B (0.00%)	105.31 KiB	332.24 KiB	91.23 KiB	▁▃▃▃▅██████
react-start.rsbuild.minimal	99.74 KiB	0 B (0.00%)	99.57 KiB	316.74 KiB	85.81 KiB	▁▃▂▂▅██████
react-start.rsbuild.minimal-iife	100.14 KiB	0 B (0.00%)	99.98 KiB	317.67 KiB	86.21 KiB	▁▃▂▂▅██████
react-start.rsbuild.full	102.96 KiB	0 B (0.00%)	102.79 KiB	326.79 KiB	88.60 KiB	▁▃▃▃▅██████
solid-start.minimal	49.71 KiB	0 B (0.00%)	49.58 KiB	152.25 KiB	43.88 KiB	▁▃▃▃▆██████
solid-start.deferred-hydration	52.97 KiB	0 B (0.00%)	49.64 KiB	160.29 KiB	46.85 KiB	▁▃▃▃▅██████
solid-start.full	55.51 KiB	0 B (0.00%)	55.38 KiB	169.30 KiB	48.97 KiB	▁▄▄▄▆██████
vue-start.minimal	71.13 KiB	0 B (0.00%)	71.00 KiB	207.37 KiB	63.03 KiB	▁▄▄▄▇██████
vue-start.full	75.13 KiB	0 B (0.00%)	75.00 KiB	220.01 KiB	66.37 KiB	▁▄▄▄▆██████

Current gzip tracks all emitted client JS chunks. Initial gzip tracks only the entry/import graph. Trend sparkline is historical current gzip ending with this PR measurement; lower is better.

[pkg-pr-new]

More templates

• tanstack-router-react-example-authenticated-routes
• tanstack-router-react-example-authenticated-routes-firebase
• tanstack-router-react-example-basic
• tanstack-router-react-example-basic-default-search-params
• tanstack-router-react-example-basic-devtools-panel
• tanstack-router-react-example-basic-file-based
• tanstack-router-react-example-basic-non-nested-devtools
• tanstack-router-react-example-react-query
• tanstack-router-react-example-basic-react-query-file-based
• tanstack-router-react-example-basic-ssr-file-based
• tanstack-router-react-example-basic-ssr-streaming-file-based
• tanstack-router-react-example-basic-virtual-file-based
• tanstack-router-react-example-basic-virtual-inside-file-based
• tanstack-router-react-example-deferred-data
• tanstack-router-i18n-paraglide
• tanstack-router-react-example-kitchen-sink
• tanstack-router-react-example-kitchen-sink-file-based
• tanstack-router-react-example-kitchen-sink-react-query
• tanstack-router-react-example-kitchen-sink-react-query-file-based
• tanstack-router-react-example-large-file-based
• tanstack-router-react-example-location-masking
• tanstack-router-react-example-navigation-blocking
• tanstack-router-react-example-quickstart
• tanstack-router-react-example-quickstart-esbuild-file-based
• tanstack-router-react-example-quickstart-file-based
• tanstack-router-react-example-quickstart-rspack-file-based
• tanstack-router-react-example-quickstart-webpack-file-based
• router-monorepo-react-query
• router-mono-simple
• router-mono-simple-lazy
• tanstack-router-react-example-scroll-restoration
• tanstack-search-validator-adapters
• tanstack-start-example-bare
• tanstack-start-example-basic
• tanstack-start-example-basic-auth
• tanstack-router-react-example-basic-authjs
• tanstack-start-example-basic-cloudflare
• tanstack-start-example-basic-react-query
• tanstack-start-example-basic-static
• tanstack-start-bun-hosting
• tanstack-start-example-clerk-basic
• tanstack-start-example-convex-trellaux
• tanstack-start-example-counter
• tanstack-start-i18n-paraglide
• tanstack-start-example-large
• tanstack-start-example-material-ui
• tanstack-start-example-rscs
• tanstack-start-streaming-data-from-server-functions
• tanstack-start-example-supabase-basic
• tanstack-start-tailwind-v4
• tanstack-start-example-trellaux
• tanstack-start-example-workos
• tanstack-router-react-example-view-transitions
• tanstack-router-react-example-with-framer-motion
• tanstack-router-react-example-with-trpc
• tanstack-router-react-example-with-trpc-react-query
• tanstack-router-vue-example-basic-jsx
• tanstack-router-vue-example-basic-file-based-jsx
• tanstack-router-vue-example-basic-file-based-sfc
• tanstack-router-solid-example-authenticated-routes
• tanstack-router-solid-example-authenticated-routes-firebase
• tanstack-router-solid-example-basic
• tanstack-router-solid-example-basic-default-search-params
• tanstack-router-solid-example-basic-devtools-panel
• tanstack-router-solid-example-basic-file-based
• tanstack-router-solid-example-basic-non-nested-devtools
• tanstack-router-solid-example-basic-solid-query
• tanstack-router-solid-example-basic-solid-query-file-based
• tanstack-router-solid-example-basic-ssr-file-based
• tanstack-router-solid-example-basic-ssr-streaming-file-based
• tanstack-router-solid-example-basic-virtual-file-based
• tanstack-router-solid-example-basic-virtual-inside-file-based
• tanstack-router-solid-example-deferred-data
• tanstack-router-solid-i18n-paraglide
• tanstack-router-solid-example-kitchen-sink
• tanstack-router-solid-example-kitchen-sink-file-based
• tanstack-router-solid-example-kitchen-sink-solid-query
• tanstack-router-solid-example-kitchen-sink-solid-query-file-based
• tanstack-router-solid-example-large-file-based
• tanstack-router-solid-example-location-masking
• tanstack-router-solid-example-navigation-blocking
• tanstack-router-solid-example-quickstart
• tanstack-router-solid-example-quickstart-esbuild-file-based
• tanstack-router-solid-example-quickstart-file-based
• tanstack-router-solid-example-quickstart-rspack-file-based
• tanstack-router-solid-example-quickstart-webpack-file-based
• @tanstack/router-solid-mono-simple
• router-solid-mono-simple-lazy
• router-solid-monorepo-solid-query
• tanstack-router-solid-example-scroll-restoration
• tanstack-solid-router-search-validator-adapters
• tanstack-solid-start-example-basic
• tanstack-solid-start-example-basic-auth
• tanstack-solid-start-example-basic-authjs
• tanstack-solid-start-example-basic-cloudflare
• tanstack-solid-start-example-basic-netlify
• tanstack-solid-start-example-basic-nitro
• tanstack-start-example-basic-solid-query
• tanstack-solid-start-example-basic-static
• tanstack-solid-start-bun-hosting
• tanstack-solid-start-example-convex-better-auth
• tanstack-solid-start-example-counter
• tanstack-solid-start-i18n-paraglide
• tanstack-solid-start-example-large
• tanstack-solid-start-streaming-data-from-server-functions
• tanstack-solid-start-example-supabase-basic
• tanstack-solid-start-tailwind-v4
• tanstack-router-solid-example-view-transitions
• tanstack-router-solid-example-with-framer-motion
• tanstack-router-solid-example-with-trpc

@tanstack/arktype-adapter

npm i https://pkg.pr.new/@tanstack/arktype-adapter@7693

@tanstack/eslint-plugin-router

npm i https://pkg.pr.new/@tanstack/eslint-plugin-router@7693

@tanstack/eslint-plugin-start

npm i https://pkg.pr.new/@tanstack/eslint-plugin-start@7693

@tanstack/history

npm i https://pkg.pr.new/@tanstack/history@7693

@tanstack/nitro-v2-vite-plugin

npm i https://pkg.pr.new/@tanstack/nitro-v2-vite-plugin@7693

@tanstack/react-router

npm i https://pkg.pr.new/@tanstack/react-router@7693

@tanstack/react-router-devtools

npm i https://pkg.pr.new/@tanstack/react-router-devtools@7693

@tanstack/react-router-ssr-query

npm i https://pkg.pr.new/@tanstack/react-router-ssr-query@7693

@tanstack/react-start

npm i https://pkg.pr.new/@tanstack/react-start@7693

@tanstack/react-start-client

npm i https://pkg.pr.new/@tanstack/react-start-client@7693

@tanstack/react-start-rsc

npm i https://pkg.pr.new/@tanstack/react-start-rsc@7693

@tanstack/react-start-server

npm i https://pkg.pr.new/@tanstack/react-start-server@7693

@tanstack/router-cli

npm i https://pkg.pr.new/@tanstack/router-cli@7693

@tanstack/router-core

npm i https://pkg.pr.new/@tanstack/router-core@7693

@tanstack/router-devtools

npm i https://pkg.pr.new/@tanstack/router-devtools@7693

@tanstack/router-devtools-core

npm i https://pkg.pr.new/@tanstack/router-devtools-core@7693

@tanstack/router-generator

npm i https://pkg.pr.new/@tanstack/router-generator@7693

@tanstack/router-plugin

npm i https://pkg.pr.new/@tanstack/router-plugin@7693

@tanstack/router-ssr-query-core

npm i https://pkg.pr.new/@tanstack/router-ssr-query-core@7693

@tanstack/router-utils

npm i https://pkg.pr.new/@tanstack/router-utils@7693

@tanstack/router-vite-plugin

npm i https://pkg.pr.new/@tanstack/router-vite-plugin@7693

@tanstack/solid-router

npm i https://pkg.pr.new/@tanstack/solid-router@7693

@tanstack/solid-router-devtools

npm i https://pkg.pr.new/@tanstack/solid-router-devtools@7693

@tanstack/solid-router-ssr-query

npm i https://pkg.pr.new/@tanstack/solid-router-ssr-query@7693

@tanstack/solid-start

npm i https://pkg.pr.new/@tanstack/solid-start@7693

@tanstack/solid-start-client

npm i https://pkg.pr.new/@tanstack/solid-start-client@7693

@tanstack/solid-start-server

npm i https://pkg.pr.new/@tanstack/solid-start-server@7693

@tanstack/start-client-core

npm i https://pkg.pr.new/@tanstack/start-client-core@7693

@tanstack/start-fn-stubs

npm i https://pkg.pr.new/@tanstack/start-fn-stubs@7693

@tanstack/start-plugin-core

npm i https://pkg.pr.new/@tanstack/start-plugin-core@7693

@tanstack/start-server-core

npm i https://pkg.pr.new/@tanstack/start-server-core@7693

@tanstack/start-static-server-functions

npm i https://pkg.pr.new/@tanstack/start-static-server-functions@7693

@tanstack/start-storage-context

npm i https://pkg.pr.new/@tanstack/start-storage-context@7693

@tanstack/valibot-adapter

npm i https://pkg.pr.new/@tanstack/valibot-adapter@7693

@tanstack/virtual-file-routes

npm i https://pkg.pr.new/@tanstack/virtual-file-routes@7693

@tanstack/vue-router

npm i https://pkg.pr.new/@tanstack/vue-router@7693

@tanstack/vue-router-devtools

npm i https://pkg.pr.new/@tanstack/vue-router-devtools@7693

@tanstack/vue-router-ssr-query

npm i https://pkg.pr.new/@tanstack/vue-router-ssr-query@7693

@tanstack/vue-start

npm i https://pkg.pr.new/@tanstack/vue-start@7693

@tanstack/vue-start-client

npm i https://pkg.pr.new/@tanstack/vue-start-client@7693

@tanstack/vue-start-server

npm i https://pkg.pr.new/@tanstack/vue-start-server@7693

@tanstack/zod-adapter

npm i https://pkg.pr.new/@tanstack/zod-adapter@7693

commit: e58444b

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/start-plugin-core/src/start-compiler/compiler.ts`:
- Around line 674-689: The reserveFunctionId logic currently only checks
reserved/generated IDs and manual owners, so a manual server function ID can
still collide with a known server function discovered by getKnownServerFns().
Update reserveFunctionId in compiler.ts to also consult the known
server-function set before accepting opts.functionId, and reject any manual ID
that matches an existing server function ID so handleCreateServerFn never reuses
an unrelated knownFns entry.

In `@packages/start-plugin-core/src/start-compiler/handleCreateServerFn.ts`:
- Around line 184-215: Resolve static template-literal IDs in the createServerFn
ID extraction path: handle no-expression template literals the same way as
string literals so `resolveStaticString`-compatible values like `id:
\`get-user\`` and `const id = \`get-user\`; createServerFn({ id })` don’t fall
through to the generic error. Update the ID resolution logic in
`handleCreateServerFn` (especially the branches that currently check
`t.isStringLiteral`, `t.isIdentifier`, and `bindingInit`) to accept the static
template-literal case and still validate it against
`MANUAL_SERVER_FN_ID_PATTERN` before returning the resolved value.
- Around line 227-250: The helper getCreateServerFnCallExpression only matches
an innermost callee named createServerFn, so aliased or namespace-resolved
factory calls are missed and manual ids are skipped. Update the resolution logic
in getCreateServerFnCallExpression (and any related createServerFn candidate
handling in handleCreateServerFn.ts) to unwrap aliased/namespace call chains and
recognize the actual factory call regardless of local import name, so { id:
"..." } is preserved instead of falling back to generated IDs.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 01e9cb30-43da-4380-bb1e-cd0ea1f81bcd

📥 Commits

Reviewing files that changed from the base of the PR and between 3d86aee and a8a2739.

📒 Files selected for processing (6)

• packages/start-client-core/src/createServerFn.ts
• packages/start-client-core/src/tests/createServerFn.test-d.ts
• packages/start-plugin-core/src/start-compiler/compiler.ts
• packages/start-plugin-core/src/start-compiler/handleCreateServerFn.ts
• packages/start-plugin-core/src/start-compiler/types.ts
• packages/start-plugin-core/tests/createServerFn/createServerFn.test.ts

[codspeed-hq]

Merging this PR will not alter performance

⚠️ Different runtime environments detected

Some benchmarks with significant performance changes were compared across different runtime environments,
which may affect the accuracy of the results.

Open the report in CodSpeed to investigate

⚡ 2 improved benchmarks
❌ 5 regressed benchmarks
✅ 173 untouched benchmarks

Warning

Please fix the performance issues or acknowledge them on CodSpeed.

Performance Changes

	Mode	Benchmark	BASE	HEAD	Efficiency
❌	Memory	mem server error-paths not-found (vue)	387.9 KB	678.7 KB	-42.84%
❌	Memory	mem server error-paths not-found (solid)	427 KB	705.5 KB	-39.48%
❌	Memory	mem server streaming-peak chunked (solid)	30.3 MB	33 MB	-8.29%
❌	Memory	mem server aborted-requests (vue)	453.7 KB	483.7 KB	-6.2%
❌	Simulation	client-route-tree-scale navigation loop (react)	74.1 ms	77.2 ms	-4.02%
⚡	Memory	mem server error-paths unmatched (react)	606.9 KB	264.4 KB	×2.3
⚡	Memory	mem server streaming-peak chunked (vue)	13.9 MB	11.1 MB	+25.48%

Tip

Investigate this regression by commenting @codspeedbot fix this regression on this PR, or directly use the CodSpeed MCP with your agent.

---

_{Comparing stable-serverfn-ids-2 (e58444b) with main (a3e24c3)¹}

Footnotes

1. No successful run was found on main (41f7bf3) during the generation of this report, so a3e24c3 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

[nx-cloud]

Nx Cloud has identified a possible root cause for your failed CI:

We investigated the three failing tasks and determined none are caused by this PR's changes. The failures stem from pre-existing environment issues: stale build artifacts in a dist directory, a hardcoded port conflict between two Vue e2e services, and an incompatible nitro-nightly package that doesn't export the required subpath. All failing projects are outside the scope of our touched projects, so no code changes are needed.

No code changes were suggested for this issue.

Trigger a rerun:

View detailed reasoning on Nx Cloud ↗

_{🎓 Learn more about Self-Healing CI on nx.dev}