Huge missed opportunity: Routes type safety should be inferred with file-based routing

[newsve]

Which project does this relate to?

Router

Describe the bug

I file this as bug because this was my expectation when I got into this project, it has been my initial understand about its type safety, I do not think this should be a new feature but the baseline, so please feel free to close this issue if I miss something.

I find the current way and the need to type the route myself in addition to the file naming and location with file-based routing tedious and not DRY:

export const Route = createFileRoute("/")({
  component: Home,
  ...
});

routeTree.gen.ts gets autogenerated all the time anyway and it could also read the file and folder structure and generate typing right from that structure with file-based routing.

I mean, the reason file-based routing got again so popular is that it is dead-simple, it isn't always the best but it is easy, intuitive and gets out of the way. And, it is less work, because you need to name files and folders anyway.

Now we have to do both, naming and decide on the location of a file + declare its route, this is more work while we could just infer the type safety from the file and folder structure.

Also fire-and-forget refactoring is not straight-forward because of the non-DRY nature, you have to manually sync route declaration and file naming and location.

Your Example Website or App

not applicable

Steps to Reproduce the Bug or Issue

not applicable

Expected behavior

Routes type safety should be automatically inferred from the real file and folder structure with file-based routing with the option to manually override typing.

Screenshots or Videos

No response

Platform

not applicable

Additional context

No response

[schiller-manuel]

typescript unfortunately does not know in which file you are currently in, so we need to tell it.
the identifier is automatically updated via router-generator (cli or plugin), so you don't need care about updating that.

[newsve]

Two questions:

1. Why did you close this so fast? Don't you want to check with other contributors about their opinion and technical feasibility? /cc @tannerlinsley
2. Not sure what you mean: When the dev server is running, something like Chokidar or any other filer watcher (you guys use nx) could check changes in the files structure and then a custom script could autogenerate routeTree.gen.ts, so this isn't about Typescript

Looking forward to your reply.

[schiller-manuel]

we got the question "why do we need to have an identifier in the route file" repeatedly, so you got the canned response for that :D
believe me, if there was a way to not have an identifier in the route file while still having fully inferred types, we had implemented it.

routeTree.gen.ts is updated automatically when you either use one of our bundler plugins and have the dev server running or when you use our CLI in watch mode.

[schiller-manuel]

typescript infers all the types already, so why should we generate them? even if we did, how would those types end up being referenced in a route file? you would have to manually annotate them.

[newsve]

typescript infers all the types already, so why should we generate them?

ts doesn't infer from the file system (files/folders/locations)

even if we did, how would those types end up being referenced in a route file?

your APIs just import them from routeTree.gen.ts

you would have to manually annotate them.

no

[tannerlinsley]

You seem to think there is a way to import types into a file route without somehow explicitly hinting to the system what file you’re in. This is, by definition, impossible, unless Typescript were to add some kind of global denoting the file name. Even if we were to import them from the route gen file, how would the route know which types to use from the N routes in that file?

We understand your frustration, and we spent countless days attempting to work around this limitation. What you see today, an auto synced single string identifier, is the minimum input we can require from a route file to identify it in the routing hierarchy.

If you have concrete ideas on how to get around this, then I suggest you build a working example to demonstrate. Telling us there is a better way without both recognizing the limitations of the language and proving your theory is unhelpful and comes across as complaining instead of constructive.

[newsve]

(A) TS primarily needs to know which paths are valid, e.g., when (B) creating API calls, links, etc.--this is, again, the primary requirement and quality of life improvement. (C) TS doesn't need to know in which file you are.

You talk about C, I about A and B and latter should be technically totally doable:

1. File watcher watches and notices some change =>
2. Script generates new routeTree.gen.ts based on the file structure in routes/ =>
3. All your APIs for B check against the just created routeTree.gen.ts

Why this is the way--now, we have only ONE source of truth, the file system, and not like with your current solution file system but no, actually the path declaration within those files (I mean why do we have file-based routing in the first place, then? Really, this is so confusing and just nor DRY from the start, there must be better ways to tackle this problem).

However, this (I am still talking about A and B) allows all key use cases the typical TS user expects:

• Settings links
• Calling API endpoints
• Submitting forms
• Refactoring is done by just changing the file-name
• Types can be still be overwritten with some custom declaration

All aforementioned use cases only need A not C.

FWIW, I wrote for myself a type checker for CT and RT which checks paths against a Drizzle/SQL data model. Was some work but works like a charm and brings huge QOLs and TS doesn't need to know in which file I am. I know, in your case we need the file watcher but I gave latter example just to illustrate one of the main use cases, using paths in consuming APIs.

We understand your frustration

This feels like a canned response on Amazon, haha. Look I am not frustrated, I am at the stage at checking out TS Start for future project/projects to migrate from. Currently I like the direction you take but I do think that a "fully type-safe" router is something else, atm there is too much manual declaration and more automation is def. possible.

So, this is more an opportunity for you to rethink and brainstorm a better version because is not "enough" to justify a migration from other solutions out there. And, I assume when looking at react-query, you have bigger ambitions. If you stay on your route, no worries nor frustration, just a missed opportunity, for you.

[tannerlinsley]

I 100% agree that there are more optimizations we can make and on the surface, your vision for how things should/could work sounds wonderful. If possible, we would obviously love to get rid of any manual declaration required to get fully inferred type-safety. To be clear though, it sounds like the bulk of this opportunity in your mind comes back to that single string value in the route file. Right? If so, I cannot stress enough that this path is automatically updated and managed for you and even produces TS errors if not properly configured. If it's about more or something else, lets pivot to those specifics.

On the topic of the file-routing path string, it's definitely not fun seeing a seemingly duplicated file path in your file route. I get that it feels unintuitive and I hope you understand that we didn't simply skip the laborious process of attempting to remove it completely. To be transparent, no less than 5 of us actively taking the time to get into the codebase, becoming deeply familiar with the constraints and context have still to this day been working on solving this small issue. Using a file-watcher and auto-management was one of the mitigation steps we took because a "remove it" solution simply wasn't possible with TypeScript. Heck, we even considered using hashes or IDs in the file as opposed to the pathname, which as long as the identifier was unique per route, would work... but now instead of seeing a meaningful pathname that looks correct, you've got developer questioning why there's some random ID in their route file... I digress.

But just for the sake of this discussion let's go deeper.

Let's say we removed that string from the file. Would we still have type-safety? Partially. It would be possible to build a system that outside of each route file (so in components or other files) would be able to auto-complete links and understand the file-structure that we crawl from the file-system. I think this is what you are getting at with your suggestions, but that only solved 50% of the type-safety problems. Let me explain with a simple route file example:

// routes/posts/$postId.tsx

import { createFileRoute, Link } from '@tanstack/react-router'

const Route = createFileRoute({
  component: () => {
    const { postId } = Route.useParams()
    // Where are the types for `postId` coming from?

    return <Link to='...' /> // This could still be autocompleted and checked, but that's about it.
  }
})

In the above example, we've removed the pathname identifier or any identifier really for knowing what file we're in. TypeScript can only reason about what we concretely supply it in our files, so without some breadcrumb back to the full routing structure, all we have is what we can inject into the file via imports, and since we are not importing anything that can uniquely and magically identify this file in our file-system (or even our route hierarchy), there is literally no way to know anything on the type-level that is unique to this file (or it's relationship to other files/routes) other than what we have defined in it.

Not only does this include the postId param that we'd expect to have from the filename, but also literally any type information from parent routes like route context, validated search params, path params, beforeLoad/loader data, etc.

I hope this is a sufficient explanation of why this is a harder problem to solve than it initially appears to be. So the real questions for anyone thinking we've sold ourselves short here or that we could do better:

• How would you get the type information specifically for this route and its unique types in relation to parent routes, child routes, etc into this file?
• What is the smallest/tersest form of this linkage that won't confuse or intimidate the developer?
• How can you do it in a way that is not forgettable or prone to typo/error?
• Can it scale in type-check performance to support tens of thousands of routes?

// routes/posts/$postId.tsx

import { createFileRoute, Link } from '@tanstack/react-router'

const Route = createFileRoute('/posts/$postId')({
  component: () => {
    const { postId } = Route.useParams()

    return <Link to='...' />
  }
})

[newsve]

Thanks for taking the time. Now, let us go back and look at the meta first:

We enter a time where full-stack TS will be the fastest way to build client-server apps. Not sure if you realized it but you spearhead this with createServerFn() which is the most advanced and no-BS implementation of this idea. All other solutions are already legacy code, they are way more cumbersome, have lol APIs and/or are more work than REST.

Even worse, REST shouldn't be derived from the file-system or some manual declaration but its source of truth should be the data model, SQL or its ORM, e.g., Drizzle, because changes in the REST endpoints ALWAYS start in the data model. So, your odd urge to have REST type safety declared on file-level just ignores reality and how rest endpoints are designed. This doesn't make sense and you develop a solution to a problem that doesn't exist, nobody needs this.

Worst, again, file-based routing was invented as a way to declare routes implicitly, your solutions fully ignores this and again, isn't DRY, and people couldn't care less about your reasoning, it just doesn't click, and will be the major bummer for general adoption, sry for the harsh words and people won't tell you this in your face, instead they just silently opt for another solution.

So, now the tl;dr:

• In a full-stack TS world we do not need REST but just server functions; your server function implementation createServerFn() is the most advanced, so you are already leading the pack
• And even if, REST shouldn't be derived from the file-structure or manual declaration but from the data model anyway, this is not your domain anymore; if you still want to get into this build a plugin for Drizzle, otherwise stay out
• A pure file watcher + script could get all type info required for 99% of relevant use cases for full-stack TS, everything beyond is pure overengineering

=> Just forget REST, it is not your domain

You do not want to know how many times I entered a rabbit-hole and came out months later realizing it was the wrong one.

[tannerlinsley]

I’m sorry, but this reads like an incoherent rambling of buzzwords. We appreciate your feedback and concern, and will do our best to take them into consideration going forward. Thank you!