Skip to content
Source
Sign inSign up
TanStack/router

perf: geting lazy?, doing less work? generate more (plus some recommendations) #1564

Mergedchorobin(GitHub profile, opens in a new tab)merged 12 commits intomain fromrefs/pull/1564/headmerged by chorobin(GitHub profile, opens in a new tab)

Getting lazy? Doing less work? and generating more (plus some recommendations)

This PR focuses more on complex routes and to some degree many routes. When I say a complex route, I mean routes which have search, params, loaders and external dependencies such as zod or other heavy TS related dependencies.

A bigger issue I've noticed in TSR is in order to get suggestions, the route tree needs to be evaluated. If your routes contain complex things that TS needs to infer like validation schemas then this can slow down TS evaluating the route tree because its hard at work on the types of the validation libraries. But for most suggestions, we only need the fullPath, we don't need to work out the search schema or the params in order to get suggestions for Link for example until search is used. The ideal scenario is we do as little as possible in order to get the suggestions we need

Show me the results!

I've updated our large filed based example to include:

  • 100 routes for absolute pathing
  • 100 routes for relative pathing
  • 100 routes for params with loader
  • 100 routes for search with loader

These include external dependencies which also do TS inference. Note the results may vary depending on what dependencies you use and how the types are written

On main:

> tsc --extendedDiagnostics

Files:                         636
Lines of Library:            38118
Lines of Definitions:        80134
Lines of TypeScript:         18481
Lines of JavaScript:             0
Lines of JSON:                   0
Lines of Other:                  0
Identifiers:                132113
Symbols:                    345367
Types:                      119980
Instantiations:            2720561
Memory used:               345796K
Assignability cache size:    56379
Identity cache size:          8114
Subtype cache size:           2022
Strict subtype cache size:       0
I/O Read time:               0.09s
Parse time:                  0.67s
ResolveModule time:          0.15s
ResolveTypeReference time:   0.00s
ResolveLibrary time:         0.02s
Program time:                1.03s
Bind time:                   0.29s
Check time:                  7.25s
printTime time:              0.00s
Emit time:                   0.00s
Total time:                  8.57s

On current branch:

> tsc --extendedDiagnostics

Files:                         636
Lines of Library:            38118
Lines of Definitions:        80143
Lines of TypeScript:         19712
Lines of JavaScript:             0
Lines of JSON:                   0
Lines of Other:                  0
Identifiers:                133346
Symbols:                    322837
Types:                      111429
Instantiations:             773068
Memory used:               327186K
Assignability cache size:    45204
Identity cache size:          8109
Subtype cache size:           2022
Strict subtype cache size:       0
I/O Read time:               0.08s
Parse time:                  0.59s
ResolveModule time:          0.12s
ResolveTypeReference time:   0.00s
ResolveLibrary time:         0.02s
Program time:                0.92s
Bind time:                   0.28s
Check time:                  5.51s
printTime time:              0.00s
Emit time:                   0.00s
Total time:                  6.71s

Getting lazy? Doing less work?

In TSR one of the largest performance bottlenecks is the route tree building. This node is important to reduce because it is directly linked to TS server suggestion times. What is contributing to this node being so slow is firstly, a lot of work upfront to evaluate search, loader, context and the others, which are possibly inferred from external libraries.

The first interesting change this PR introduces is not a breaking one but introducing a new signature to addChildren. addChildren accepts a tuple of routes like the following:

route.addChildren([childRoute1, childRoute2])

addChildren also in addition can now accept an object route.addChildren({ childRoute1, childRoute2 }).

Why this change? Well, it looks like tuples seem to be forcing TS to be doing something in each route which is quite slow and it gets worse with different external dependencies, where objects seem to be more cheap or perhaps more lazy in nature, maybe there's also caching involved? Depending on the libraries used in for example validateSearch, you may notice a difference in performance improvements.

For example, using valibot instead of zod in the above example with addChildren that accept a tuple

> tsc --extendedDiagnostics

Files:                          638
Lines of Library:             38680
Lines of Definitions:         86278
Lines of TypeScript:          19809
Lines of JavaScript:              0
Lines of JSON:                    0
Lines of Other:                   0
Identifiers:                 141166
Symbols:                     270865
Types:                        90876
Instantiations:            22514251
Memory used:                310778K
Assignability cache size:     33466
Identity cache size:           7787
Subtype cache size:            2830
Strict subtype cache size:        1
I/O Read time:                0.09s
Parse time:                   0.63s
ResolveModule time:           0.14s
ResolveTypeReference time:    0.01s
ResolveLibrary time:          0.02s
Program time:                 1.03s
Bind time:                    0.30s
Check time:                  14.66s
printTime time:               0.00s
Emit time:                    0.00s
Total time:                  15.99s

Now with addChildren that accepts an object

> tsc --extendedDiagnostics

Files:                         638
Lines of Library:            38680
Lines of Definitions:        86278
Lines of TypeScript:         19813
Lines of JavaScript:             0
Lines of JSON:                   0
Lines of Other:                  0
Identifiers:                141170
Symbols:                    269855
Types:                       90640
Instantiations:            1093144
Memory used:               316056K
Assignability cache size:    33455
Identity cache size:          7787
Subtype cache size:           2830
Strict subtype cache size:       1
I/O Read time:               0.09s
Parse time:                  0.68s
ResolveModule time:          0.14s
ResolveTypeReference time:   0.01s
ResolveLibrary time:         0.02s
Program time:                1.09s
Bind time:                   0.35s
Check time:                  5.35s
printTime time:              0.00s
Emit time:                   0.00s
Total time:                  6.79s

That's a big difference between tuples and objects. I'm still not totally sure why tuples behave this way or if I'm even correct about my assumptions but to me it looks like tuples are forcing some kind of extra work the TS compiler is doing and its related to validateSearch and how the types of the external library are likely written.

Profile

The first link that is checked by TS has to evaluate the route tree and it looks like this with addChildren accepting a tuple

image

The same node with addChildren accepting an object looks like this

image

But thats not the end of the story. Each individual Link is also faster with children as an object. Each Link is checked with the following time when addChildren accepts a tuple

image

And each Link is checked with the following time with addChildren accepts an object

image

As mentioned before. 30ms might not seem like much. But if you have 30ms for every Link in your code base, it quickly accumulates. 4ms is a huge difference in these cases

In this PR I have switched file based routing over to using objects automatically for a default performance boost. Code based can opt into the signature.

Other stuff

Generating more

File based routing previously has done a lot of string interpretation on the type level in order to calculate things like fullPath, path, id etc. Template literal types are expensive for the compiler and generally in file based routing, these strings can be generated directly by the generator without hurting inference. This speeds up creating routes

Improve params parsing

A more direct implementation of path params parsing without any additional splitting or mapped types

What can blow up your TS Performance

With TSR you want to narrow to the most relevant routes. This means using from and to on Link or other API's.

For example, <Link search={{ page: 0 }} /> will increase the type checking time on this link because TSR will resolve search to all possible routes (a union of all search params) and will therefore spend longer type checking it. This depends on the size of your route tree and how many search params you have but on our large example, I noticed a single Link would type check in roughly 100ms.

It is better to narrow the route as much as you can <Link from={Route.fullPath} search={{ page: 0 }} /> with from or to. In this case the time type checking Link went down to 9ms.

This same logic also applies to LinkOptions. If you're using types from TSR which are by default not narrowed to a route then this can also blow up TS performance when merging this props with Link. Just remember that when from or to is not specified then things can start slowing down, so definitely try to do it as little as possible.

    1. ☁️ Nx Cloud Report

      CI is running/has finished running commands for commit 236d63c417f90fa44bf95e3fc16bd727c9634286. As they complete they will appear below. Click to see the status, the terminal output, and the build insights.

      📂 See all runs for this CI Pipeline Execution


      ✅ Successfully ran 2 targets

    2. Sent with 💌 from NxCloud.

  • Still some work needs to be done so not ready just yet

  • should the object vs array syntax be configurable?

  • maybe should be renamed? since it now only handles allParams

  • we should add that What can blow up your TS Performance section into the documentation

  • we should add that What can blow up your TS Performance section into the documentation

    Definitely. Think we need to write a section on it so they can go to it and be able to resolve common problems

  • I realized these constraints were not necessary because they were just constrained to {} which is already extremely loose

  • I'm not sure. I like the idea that if we can confirm one way of building the route tree is more performant then we should prefer that for file based because I'm not sure if users care in this case if it is a tuple or object?

  • packages/router-generator/tests/generator/nested-layouts/routeTree.expected.ts line 144
    @@ -138 +144 @@
    138144 declare module '@tanstack/react-router' {

    @schiller-manuel I've added conditions for the tests in the generator for fullPath, id, path. Are there any situations missing here that I should add?

  • Resolvedby chorobin(GitHub profile, opens in a new tab)
  • ok, let's default to objects for filebased routing

  • packages/router-generator/src/generator.ts line 593
    @@ -583,4 +583,11 @@
    583583 interface FileRoutesByPath {
    584584 ${routeNodes
    585585 .map((routeNode) => {
    586- return `'${removeTrailingUnderscores(routeNode.routePath)}': {
    586+ const filePathId = removeTrailingUnderscores(routeNode.routePath)
    587+ const id = filePathId
    588+ const fullPath = removeGroups(
    589+ removeUnderscores(removeLayoutSegments(routeNode.routePath)) ?? '',
    590+ )
    591+
    592+ return `'${filePathId}': {
    593+ id: '${id}'

    I thought id was slightly different?

    SeanCassierecommented

    Correct me if I'm wrong, but you are explicitly setting these values on the declaration so you don't need to resolve the inference again via the TS-resolve types, yes? Edit: Ignore this comment, I didn't properly read the PR description.

    SeanCassierecommented

    Also, just want to confirm that we don't end up in a scenario that a created route configuration (not route type declaration) doesn't ever have both an id and a path.

    Like:

    const fooRoute = fooImport.update({
      id: 'foo',
      path: '/foo'
    })

    This only affects the type that's printed for module declaration.

    I'm not sure if I get your point. I think file based routing always had id and path in the types?

    SeanCassierecommented

    Check more into this, it looks good.

    Just wanted to make sure we weren't modifying anything in route configuration, and only touching stuff on the type declaration.

  • chorobin(GitHub profile, opens in a new tab)replied on packages/router-generator/src/generator.ts line 593

    I thought id was slightly different?

  • packages/react-router/src/fileRoute.ts line 89
    @@ -150,20 +83,7 @@
    15083 TFullSearchSchemaInput = ResolveFullSearchSchemaInput<
    15184 TParentRoute,
    15285 TSearchSchemaUsed
    15386 >,
    15487 TFullSearchSchema = ResolveFullSearchSchema<TParentRoute, TSearchSchema>,
    15588 TParams = Record<ParsePathParams<TPath>, string>,
    156- TAllParams = MergeFromFromParent<
    157- TParentRoute['types']['allParams'],
    158- TParams
    159- >,
    160- TRouteContextReturn extends
    161- RouteConstraints['TRouteContext'] = RouteContext,
    162- TRouteContext = [TRouteContextReturn] extends [never]
    163- ? RouteContext
    164- : TRouteContextReturn,
    165- TAllContext = Assign<
    166- IsAny<TParentRoute['types']['allContext'], {}>,
    167- TRouteContext
    168- >,
    169- TRouterContext extends RouteConstraints['TRouterContext'] = AnyContext,
    89+ TAllParams = ResolveAllParamsFromParent<TParentRoute, TParams>,

    It's a bit faster to name all complex types

  • Don't merge yet. Need to double check some things. Ideas 💡

  • SeanCassiere reviewed

    I don't have the best understanding of all the ts-stuff we do with the router, but trying it out on my machine with out examples, the functionality works identical to what it was like before.

    Left some comments, but nothing too crazy, all-in-all amazing, amazing, amazing, work @chorobin 🙌🏼!

    SeanCassierecommented

    Yeah, I agree. Plus we've been consistent about the fact that whatever is output from the router-generator is in our control anyway.

    SeanCassierereplied on packages/router-generator/src/generator.ts line 593

    Correct me if I'm wrong, but you are explicitly setting these values on the declaration so you don't need to resolve the inference again via the TS-resolve types, yes? Edit: Ignore this comment, I didn't properly read the PR description.

    SeanCassierereplied on packages/router-generator/src/generator.ts line 593

    Also, just want to confirm that we don't end up in a scenario that a created route configuration (not route type declaration) doesn't ever have both an id and a path.

    Like:

    const fooRoute = fooImport.update({
      id: 'foo',
      path: '/foo'
    })

    This only affects the type that's printed for module declaration.

    SeanCassierereplied on packages/router-generator/src/generator.ts line 588

    Checking the "kitchen-sink-file-based" example, currently the /router-group route has its id showing up as /route-group and NOT /(this-folder-is-not-in-the-url)/route-group.

    @chorobin not sure if you want the id value here to represent the what the route id is at runtime in the router, but if so, you'd probably want to remove the groups here as well.

    packages/react-router/src/link.tsx line 61
    @@ -56,6 +58,4 @@
    5658 : never
    5759 : never
    5860
    59-export type ParsePathParams<T extends string> = keyof {
    60- [K in Trim<Split<T>[number], '_'> as K extends `$${infer L}`
    61- ? L extends ''
    61+export type ParsePathParams<
    SeanCassierecommented

    This comment may not really belong here at this line, rather it's something I noticed about the link component when testing out the PR.

    In the "kitchen-sink-file-based" example, using a <Link> component it accepts the following to values.

    1. /route-group
    2. route-group

    1 works as expected, but 2 then says it requires params.

    Property 'params' is missing in type '{ to: "route-group"; }' but required in type 'MakeRequiredPathParams<Router<Route<any, "/", "/", string, "__root__", RootSearchSchema, RootSearchSchema, RootSearchSchema, RootSearchSchema, ... 10 more ..., { ...; }>, TrailingSlashOption, Record<...>, Record<...>>, string, "route-group">'.ts(2741)

    Also, something else, I noticed is that the from property doesn't accept just route-group, only allows /route-group unlike the to property shown above.

    Yeah, its a separate issue I'm going to be fixing in a separate PR. Its a bug on main as well.

    examples/react/basic-file-based/src/routeTree.gen.ts line 73
    @@ -73 +73 @@
    7373 declare module '@tanstack/react-router' {
    SeanCassierecommented

    We'll need to generate the route-trees on all the file-based examples as well and start migrating all the code-based examples over to the object-syntax.

    while I agree we should re-generate the route-trees of file based examples, I don't think we MUST migrate the code based ones.

    Let's slow down a bit. I'm exploring another idea that I really hope means we can not introduce a new signature. But we will see! I'm not sure if it'll work yet

    Ok. Turns out the idea is again limited by the children being tuples, it likely forcing unnecessary instantiations...

    We need to keep the signature to allow objects for children

    docs/framework/react/guide/type-safety.md line 144Outdated
    @@ -112,0 +124,21 @@
    124+<Link to="." search={{ page: 0 }} />
    125+<Link search={{ page: 0 }} />
    126+```
    127+
    128+**These examples are bad for TS performance**. Thats because `search` resolves to a union of all `search` params for all routes and TS has to check whatever you pass to the `search` prop against this potentially big union. As your application grows, this check time will increase linearly to number of routes and search params. We have done our best to optimise for this case (typescript will typically do this work once and cache it) but the initial check against this large union is expensive. This also applies to `params` and other API's such as `useSearch`, `useParams`, `useNavigate` etc
    129+
    130+Instead you should try to narrow to relevant routes with `from` or `to`
    131+
    132+```tsx
    133+<Link from={Route.fullPath} to=".." search={{page: 0}} />
    134+<Link from="/posts" to=".." search={{page: 0}} />
    135+```
    136+
    137+Remember you can always pass a union to `to` or `from` to narrow the routes you're interested in. You can also pass branches to `from` to be more loose.
    138+
    139+```tsx
    140+const from: '/posts/$postId/deep' | '/posts/' = '/posts/'
    141+<Link from={from} to='..' />
    142+```
    143+
    144+### Consider using the object syntax of `createChildren`
    SeanCassierecommented

    I believe this should be addChildren

  • Also, we probably want to using the feat: or refactor: prefix on the commit name. Not sure if we are using conventional commits or angular commits, but if I've not mistaken on one of them using perf: triggers a major version bump.

  • SeanCassierecommented

    @SeanCassiere in light of #1584, can you please review this?

    Trying out the changes from my previous PR on this branch yielded no collisions or regressions that I could observe on that specific layout route behaviour.

    That being said, @chorobin once the merge conflict has been resolved, you'd want to rebase and confirm the tests I introduced in that PR still work.

  • docs/framework/react/guide/type-safety.md line 116Outdated
    @@ -110,3 +110,7 @@
    110110 },
    111111 })
    112112 ```
    113+
    114+## Performance Recommendations
    115+
    116+As your application scales, typescript check times will naturally increase. There are a few things to keep in mind when your application scales to keep your TS check times down.
  • docs/framework/react/guide/type-safety.md line 128Outdated
    @@ -110,3 +110,19 @@
    110110 },
    111111 })
    112112 ```
    113+
    114+## Performance Recommendations
    115+
    116+As your application scales, typescript check times will naturally increase. There are a few things to keep in mind when your application scales to keep your TS check times down.
    117+
    118+### Narrow to relevant routes as much as you possibly can
    119+
    120+Consider the following usage of `Link`
    121+
    122+```tsx
    123+<Link to=".." search={{ page: 0 }} />
    124+<Link to="." search={{ page: 0 }} />
    125+<Link search={{ page: 0 }} />
    126+```
    127+
    128+**These examples are bad for TS performance**. Thats because `search` resolves to a union of all `search` params for all routes and TS has to check whatever you pass to the `search` prop against this potentially big union. As your application grows, this check time will increase linearly to number of routes and search params. We have done our best to optimise for this case (typescript will typically do this work once and cache it) but the initial check against this large union is expensive. This also applies to `params` and other API's such as `useSearch`, `useParams`, `useNavigate` etc
  • OutdatedResolvedby chorobin(GitHub profile, opens in a new tab)
  • OutdatedResolvedby chorobin(GitHub profile, opens in a new tab)
  • can we provide instructions how to type the params of functions that want to receive LinkProps?

  • schiller-manuel(GitHub profile, opens in a new tab)replied on examples/react/basic-file-based/src/routeTree.gen.ts line 73

    while I agree we should re-generate the route-trees of file based examples, I don't think we MUST migrate the code based ones.

  • packages/react-router/src/index.tsx line 67Outdated
    @@ -71,3 +64,4 @@
    7164 type UseLinkPropsOptions,
    7265 type ActiveLinkOptions,
    7366 type LinkProps,
    67+ type LinkComponentProps,

    do we really want to export this type? what would this be used for?

  • chorobin(GitHub profile, opens in a new tab)replied on examples/react/basic-file-based/src/routeTree.gen.ts line 73

    Let's slow down a bit. I'm exploring another idea that I really hope means we can not introduce a new signature. But we will see! I'm not sure if it'll work yet

  • chorobin(GitHub profile, opens in a new tab)replied on packages/router-generator/src/generator.ts line 588

    Thanks for catching that. I've updated the tests and the code to remove the route groups

  • chorobin(GitHub profile, opens in a new tab)replied on packages/router-generator/src/generator.ts line 593

    I'm not sure if I get your point. I think file based routing always had id and path in the types?

  • chorobin(GitHub profile, opens in a new tab)replied on examples/react/basic-file-based/src/routeTree.gen.ts line 73

    Ok. Turns out the idea is again limited by the children being tuples, it likely forcing unnecessary instantiations...

    We need to keep the signature to allow objects for children

  • Also, we probably want to using the feat: or refactor: prefix on the commit name. Not sure if we are using conventional commits or angular commits, but if I've not mistaken on one of them using perf: triggers a major version bump.

    I've never heard of this. In conventional commits I thought you had to explicitly mention ! or BREAKING CHANGE to bump major version

  • Added to the performance recommendations

  • chorobin(GitHub profile, opens in a new tab)replied on packages/react-router/src/link.tsx line 61

    Yeah, its a separate issue I'm going to be fixing in a separate PR. Its a bug on main as well.

  • packages/react-router/src/link.tsx line 196
    @@ -184,4 +191,6 @@
    184191 TTo extends string = '',
    185192 TMaskFrom extends RoutePaths<TRouter['routeTree']> | string = TFrom,
    186193 TMaskTo extends string = '',
    187-> = ToSubOptions<TRouter, TFrom, TTo> & {
    194+> = ToSubOptions<TRouter, TFrom, TTo> & MaskOptions<TRouter, TMaskFrom, TMaskTo>
    195+
    196+export interface MaskOptions<

    Naming all of these types helps TS cache stuff when passing LinkProps to a Link. Slightly more optimised

  • SeanCassierereplied on packages/router-generator/src/generator.ts line 593

    Check more into this, it looks good.

    Just wanted to make sure we weren't modifying anything in route configuration, and only touching stuff on the type declaration.

  • Sign in to join this conversation.