fix(react-router): memo of useLinkProps

[Sheraff]

Important

I'm not saying we should merge this, I just want to demonstrate how it would look to enable memoization in this hook

The issue

Currently, the useLinkProps hook is either called from the <Link> component, or explicitly in userland.

• from the <Link> component (which is equivalent to createLink):

  (props, ref) => {
    const { _asChild, ...rest } = props
    useLinkProps(rest, ref)

• in userland (just a guess as to how it's probably used)

  useLinkProps({ foo, bar, baz })

In both cases, the options object will always be a new object on every render.

In addition to this, the options object is also internally overwritten which forces it to always be a new object:

  options = {
    from: parentRouteId,
    ...options,
  }

This means that some of the memoization inside useLinkProps is ineffective. For example:

  const next = React.useMemo(
    () => router.buildLocation(options as any),
    [router, options, currentSearch],
  )

or

  const doPreload = React.useCallback(() => {
    router.preloadRoute(options as any).catch((err) => {
      console.warn(err)
      console.warn(preloadWarning)
    })
  }, [options, router])

And this instability cascades down to more things, like useLayoutEffect and useIntersectionObserver

Possible solutions

Because of this "instability" of the options object, using useMemo / useCallback adds cost, and doesn't bring any benefits.

There are 2 possible avenues for improving this situation:

1. stabilize the options object to make memoization possible. This is what this PR does, but it also demonstrates that it could potentially be verbose, and maybe pointless (some objects might have a shape that makes them somewhat inappropriate for memoization like search, params, ... unless we start resorting to ugly patterns of dynamic dependency arrays). It's not ideal, but for some situations it could be better than nothing.

2. remove most of the memoization. Since it is currently pure cost / no benefits, we could reduce the cost. This means that useLayoutEffect and useIntersectionObserver will keep re-executing on every render for now. This solution is most likely a bet on the react-compiler to solve this in the near future. As a reminder, the react-compiler will not compile libraries from the application's pipeline so this would have to be included in tanstack's publishing pipeline

React Compiler can also be used to compile libraries. Because React Compiler needs to run on the original source code prior to any code transformations, it is not possible for an application’s build pipeline to compile the libraries they use. Hence, our recommendation is for library maintainers to independently compile and test their libraries with the compiler, and ship compiled code to npm.

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 5025710.

Command	Status	Duration	Result
nx affected --targets=test:eslint,test:unit,tes...	✅ Succeeded	6m 19s	View ↗
nx run-many --target=build --exclude=examples/*...	✅ Succeeded	1m 19s	View ↗

---

☁️ Nx Cloud last updated this comment at 2025-02-07 22:34:52 UTC

[pkg-pr-new]

Open in Stackblitz

More templates

• tanstack-router-react-example-authenticated-routes
• tanstack-router-react-example-basic-default-search-params
• tanstack-router-react-example-basic
• tanstack-router-react-example-basic-file-based
• tanstack-router-react-example-basic-file-based-codesplitting
• tanstack-router-react-example-basic-react-query-file-based
• tanstack-router-react-example-basic-ssr-file-based
• tanstack-router-react-example-react-query
• 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-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-navigation-blocking
• tanstack-router-react-example-location-masking
• 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
• router-monorepo-react-query
• tanstack-router-react-example-quickstart-webpack-file-based
• router-mono-simple
• router-mono-simple-lazy
• tanstack-router-react-example-scroll-restoration
• tanstack-search-validator-adapters
• tanstack-start-example-basic
• tanstack-start-example-basic-react-query
• tanstack-start-example-basic-auth
• tanstack-start-example-basic-rsc
• tanstack-start-example-clerk-basic
• tanstack-start-example-convex-trellaux
• tanstack-start-example-large
• tanstack-start-example-counter
• tanstack-start-example-supabase-basic
• tanstack-start-example-trellaux
• tanstack-router-react-example-with-trpc
• tanstack-router-react-example-with-framer-motion
• tanstack-router-react-example-with-trpc-react-query

@tanstack/arktype-adapter

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

@tanstack/create-router

npm i https://pkg.pr.new/@tanstack/create-router@3365

@tanstack/directive-functions-plugin

npm i https://pkg.pr.new/@tanstack/directive-functions-plugin@3365

@tanstack/create-start

npm i https://pkg.pr.new/@tanstack/create-start@3365

@tanstack/history

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

@tanstack/react-cross-context

npm i https://pkg.pr.new/@tanstack/react-cross-context@3365

@tanstack/eslint-plugin-router

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

@tanstack/react-router

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

@tanstack/react-router-with-query

npm i https://pkg.pr.new/@tanstack/react-router-with-query@3365

@tanstack/router-cli

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

@tanstack/router-core

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

@tanstack/router-devtools

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

@tanstack/router-generator

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

@tanstack/router-plugin

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

@tanstack/router-utils

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

@tanstack/router-vite-plugin

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

@tanstack/server-functions-plugin

npm i https://pkg.pr.new/@tanstack/server-functions-plugin@3365

@tanstack/start

npm i https://pkg.pr.new/@tanstack/start@3365

@tanstack/start-api-routes

npm i https://pkg.pr.new/@tanstack/start-api-routes@3365

@tanstack/start-client

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

@tanstack/start-config

npm i https://pkg.pr.new/@tanstack/start-config@3365

@tanstack/start-plugin

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

@tanstack/start-router-manifest

npm i https://pkg.pr.new/@tanstack/start-router-manifest@3365

@tanstack/start-server

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

@tanstack/start-server-functions-client

npm i https://pkg.pr.new/@tanstack/start-server-functions-client@3365

@tanstack/start-server-functions-fetcher

npm i https://pkg.pr.new/@tanstack/start-server-functions-fetcher@3365

@tanstack/start-server-functions-handler

npm i https://pkg.pr.new/@tanstack/start-server-functions-handler@3365

@tanstack/start-server-functions-server

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

@tanstack/start-server-functions-ssr

npm i https://pkg.pr.new/@tanstack/start-server-functions-ssr@3365

@tanstack/valibot-adapter

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

@tanstack/virtual-file-routes

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

@tanstack/zod-adapter

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

commit: 5025710

[schiller-manuel]

some objects might have a shape that makes them somewhat inappropriate for memoization like search, params

what problem does their shape cause?
we try to keep referential stability for those using replaceEqualDeep as much as possible, so them being object should not be an issue.

[Sheraff]

some objects might have a shape that makes them somewhat inappropriate for memoization like search, params

what problem does their shape cause? we try to keep referential stability for those using replaceEqualDeep as much as possible, so them being object should not be an issue.

These are userland objects, they're not coming from hooks with structural sharing. For example:

<Link
  to="/foo/$a/$b"
  params={{ a: 'a', b: 'b' }}
  search={{ hello: 'world' }}
>

[schiller-manuel]

oh right... then they need to memoized by the caller :(

[Sheraff]

oh right... then they need to memoized by the caller :(

Yeah, but I doubt most codebases will be this stringent on memoization (until everyone has the react-compiler that is!)