Should TanStack router rewrite route files?

[msssk]

I think the router plugin re-writing route files is very bad DX. If an issue is found in a route file the route file should be left alone. Log the issue, ideally with a link to relevant documentation about resolving the issue. Do not presume to know better than I do how I want my routes to be defined. If I have made a mistake help me understand how to fix it, do not impose an undesirable fix on me.

[tannerlinsley]

I'm not quite sure what you're describing here. Are you referring to automatic code splitting?

[msssk]

The router plugin will re-write route files if the route does not match the file name (and other conditions that are not clearly documented). I don't ever want my route files re-written.

file: route1_.ts

export const Route = createFileRoute('/route1')()

The plugin will re-write the file, ignoring the existing indentation settings and change '/route1' to '/route1_'.

That example seems innocuous at a glance, it's just fixing things, right? But maybe not, maybe the author does not want a non-nested route?

There is a case where the plugin will change a route from '/somevalue' to '/somevalue/' which is not what I want. I don't know why I can't have '/somevalue' and can't find any documentation why the plugin doesn't like '/somevalue'. Having the plugin just "fix" this for me is infuriating - I would rather know what I need to do to get my desired routing working, not have the plugin change my routing.

[tannerlinsley]

This is a misunderstanding of File Route configuration. The auto fixing is so you don’t have to double maintain route paths. The file system (if you’re using file based routing) is the source of truth, not the ID generated for createFileRoute(id). That ID is honestly just there to teach TypeScript about the file system (because it has no idea about it) and give you the automatic type inference without any additional setup.

I do agree we need to improve the docs around file based routing.

[msssk]

I understand the design complications of file-based routing (and appreciate the benefits), but I think it is normal for a programmer to consider their code to be the source of truth. It is bad DX for a tool that is advertised as auto-generating the route tree to also attempt to fix my code (and do it wrongly). If the route id does not match the file name then routing should be broken until the code is fixed - and the plugin should tell the developer that there is a mismatch and link to relevant documentation.

It would also be very nice for the documentation to explain why /routeId is sometimes valid and sometimes not (the plugin changes it to /routeId/).

[tannerlinsley]

• That single ID in createFileRoute is necessary for type-script to work, and is a very small price to pay for that functionality, especially considering we manage it for you.
• The source of truth for file-based routing is not your source code, but where it lives in the file structure, so there is nuance there.
• The routeId that is injected into your code is derived from that source of truth, the file system.
• Since this auto-fix logic is necessary for typescript, we wouldn't be able to show a type error if misconfigured
• The only option if we didn't sync it for you would be to error the entire build.

However, I would wager this would produce an even more frustrating experience:

Error: Expected Route ID `/route1` inside file `route1_` to be `/route1_`.

• Why would we expect the user to ensure this detail stays in sync?
• If the system knows what it should be, and there are no other valid options for the value, shouldn't the system be responsible for it's management?

And that's just considering your basic one at a single nesting level. Get into deeper paths and you'll notice that the ID needs to be a fully from-root unique representation of where the file sits in the route tree representation. Expecting you to know that full path, type it perfectly, and effectively repeat your intentions (that are already explicit via the file-system structure and file name) would redundant and annoying for developers.

You may be correct that this is an education issue, and I'll take into consideration your feedback for the docs. But I firmly believe this is a misinformed take on the file-based routing conventions for TanStack Router.

To answer a few more questions:

• The difference between /routeId and /routeId/ is significant. The former represents a layout route that may wrap an index route and other children and the latter specifically represents an index route or exact match of /routeId/ with no child routes matching. They are quite literally different routing structures with different loaders, search params, etc so it's important to keep them distinct.
• I noticed in your OP that you mentioned "what if the dev doesn't want a non-nested route", to which the answer would be to remove the trailing _ from the route file name, since the file name is the source of truth for the path. Prefixed and trailing _ are used to denote special types of routing structures and do not contribute to the actual pathname of the route, which is well documented.

I'm still not sure where router is fixing your code "wrongly". It will sync the string to represent the file structure you have given. If you name a file route1_.tsx, the route ID will be /route1_ and the matching path will be /route1

[msssk]

Sorry for my lack of clarity - I understand and accept that the file names are the source of truth. When I talk about programmers thinking of their code as the source of truth I am talking about DX. Even knowing that file-based routing is dependent on the file naming, decades of programming have ingrained an experience of source code being the source of truth. If my source code is correct the results are correct. If my source code is incorrect the results are incorrect.

For me, I would definitely prefer for my routing to be broken if my source code is incorrect. The router and/or the plugin should inform me of the route id mismatch, but not automatically "fix" it for me.

It is well documented, and expected, that the router plugin generates the route tree. I am grateful for it. I started without file-based routing, tired of managing the route tree myself, and switched to file based routing. Over the course of a year I have enjoyed using TanStack router and created dozens of routes and the vast majority of the time I manually entered the correct route id. So it came as a shock, and an unwelcome developer experience, when suddenly the source code that I wrote (route ids) was being changed automatically.

I understand that /route and /route/ are different paths, what is not clear is what the distinction means to TanStack. I desire a route tree like so:

• /route - render a component
• /route/child - render the component for /route and in the outlet render the component for child

The documentation makes it appear very straightforward to do this, so I set it up and then discover to my dismay that the plugin has changed /route to /route/. (It has also rewritten the route file without respecting the existing indentation in use.)

Suggestions:

• Make route id fixing opt-in (or at least give the option to opt out)
• Clearly document that the router plugin will not only generate the route tree, but may also rewrite route files to fix the route id
• Use existing indentation and line endings when rewriting route files to fix route ids
• Clarify what kind of routing is valid in the documentation - https://tanstack.com/router/latest/docs/framework/react/guide/file-based-routing#directory-routes indicates that /posts (posts/index.tsx) and /posts/$postId (posts/$postId.tsx) is valid. In my experience /posts was overwritten as /posts/; I had to use /posts.tsx instead of /posts/index.tsx