V2

[tannerlinsley]

Moving away from classes

Classes are great for defining types and functionality in one go, but they're not very friendly to destructuring and compositional/functional APIs. The following changes would unify the router API to be less class-y and more function-y.

• Deprecate new Router in favor of createRouter
• Deprecate new RootRoute in favor of createRootRoute
• Deprecate new Route in favor of createRoute
• Deprecate new FileRoute(path).createRoute(options) in favor of createFileRoute(path)(options)
• Deprecate new RouteApi in favor of getRouteAPI
• Deprecate FileRouteLoader in favor of the new createLazyFileRoute and Route.lazy functions

JSDoc Annotations

• Add inline JSDoc annotations to most of the API to help with IDE documentation
• Potentially auto-generate API reference documentation

Code Splitting

• Deprecate individual code-split properties component, errorComponent and pendingComponent in favor of createLazyFileRoute and Route.lazy()

Code-Generation

• Refactor generated code to be smaller and easier to follow.

Server

• Deprecate escapeJSON in favor jsec.
• Deprecate dehydrateData in favor of injectHtml.
• Deprecate hydrateData in favor of injectHtml.

General

• Deprecate 'Not-Found Routes' in favor of route-specific notFoundComponent. See migration guide here.
• Deprecate global on NotFoundError in favor of routeId.
• Deprecate href in redirect() in favor of statusCode.
• Deprecate ErrorRouteProps in favor of ErrorComponentProps.
• Deprecate the navigate function as an argument in the beforeLoad and loader callbacks, in favor of using throw redirect(...) and throw notFound(...).

[SeanCassiere]

In addition to the migration from classes to the more compositional/function approach, could we ensure consistent naming of all the user-facing APIs?
Off the top of my head, the FileRouteLoader function is one which could be better named as createFileRouteLoader.

When a timeline for v2 is more clear we could take stock and compile a list of user-facing APIs for renaming.

[tannerlinsley]

Added to the list ✅

[SeanCassiere]

It's something I saw on X/Twitter a few months back and a variation of which I saw today. It's about the idea of utilizing JSDocs for giving the user documentation right in their code editor.

Approach 1

For an easy option, we could do what Tanstack Table did, and add links to the JSDoc comments on each property which would direct the user to the individual headings on the Documentation site.

Screenshot

This would be rather a quick task and has a significantly reduced buy-in compared to approach 2.

Approach 2

We could ship the entire Reference docs to the user through JSDocs by setting them on the properties.

It gives the user the benefit of not having to even visit the reference site, whilst retaining the exact version of documentation needed for the package version they are on.

However, this approach would require investigation into how we could extract the comments from JSDocs into usable static documentation, as well as the CI steps that would come with it. Also, on how this would affect bundle sizes.

[tannerlinsley]

I've updated the items to include these things :)

[SeanCassiere]

Saw this from Ryan today: https://twitter.com/ryanflorence/status/1785440251508572608

[SeanCassiere]

Adding a helper function similar to throw redirect() to trigger the closest notFoundRoute from the beforeLoad and loader functions.

Use case I'm looking at:

// /postId
const Route = new Route({
  ...,
  loader: async ({ params: { postId } }) => {
    const post = await getPost(postId);

    if (!post) throw notFound();

    return postl
  }
})

The behaviour of this helper during the preload state is something to be considered.

[SeanCassiere]

Personally, I don't believe this throw should do anything during a preload state, and should be suppressed (do not trigger the NotFoundRoute).
However, a valid argument could be made that since both the beforeLoad and loader functions are given the preload state as an argument, that it could be left up to the user to decide how they want it to behave.

[tannerlinsley]

We have special logic internally to ignore redirects during preloads. It would be very easy to do the same for notFound

[tannerlinsley]

I updated this with the work I just did in v1. All of it should be non-breaking.

[sohamnandi77]

[tannerlinsley]

https://tanstack.com/router/v1/docs/framework/react/guide/code-splitting#using-the-lazytsx-suffix

[auvansang]

I'm thinking about decorate LOL, like .NET
@route("/xxxx", ....other args)
export function Component(props) {}

[SeanCassiere]

A few things on this:

Since the library is not "Typescript-only", this wouldn't be possible the Javascript decorators proposal is still in Stage 3 of the RFC process and right now has 0% browser availability it wouldn't be possible to implement without requiring devs to also add in a polyfill.

...and even when it does come in and if it receives good browser support, it'd then be a question of looking at the state of the JS ecosystem and the user perception of dealing with a new interface like what decorators bring to the table. Since it'll essentially be brand new to the eco-system as a whole (outside of the Nest and TypeORM peeps) people may find it too confusing.

Lastly, and most importantly, since the Typescript part of this Router is all about runtime type-checking and dev type-inference which is a big seller for the library, it remains to be seen if the current level of DX can be implemented using the future official Decorators implementation. Since any regression is the type-inference from the current DX will be a big "no-no".

TLDR; I wouldn't hold out too much hope on it at least until it has browser implementation. And even when it does it'll be based on whether Tanner sees any tangible benefits from adopting it into the codebase.

[tannerlinsley]

I can tell you right now that I don’t plan on adopting or supporting decorators unless they somehow become a very very widely used pattern across multiple frameworks.

[auvansang]

One more things, I'm adapting to TanStack Router (previously .NextJs), But I still no see a document about routing with Markdown file

[SeanCassiere]

Sorry, didn't see this till today... Better late than never I guess.

When it comes to markdown, you'd need a way to fetch and render the markdown in React. Using server rendering, you could fetch the markdown (from a file or a CMS) and pass it to a renderer like react-markdown (or something that does the job of taking markdown and turning it into HTML).

In the aspect of the Router, this is all possible (with server rendering), but you'd need to wire it up to meet your exact use case.

We probably won't go down the route of markdown processing with Router, since that is an implementation detail that can vary quite a bit.

That being said if you are interested in doing so, the TanStack/tanstack.com repo is a pretty excellent example of fetching markdown content over the wire and rendering it on the client. You'd probably want to adjust it to read from the file-system instead.

[mustakimkr]

Hey @tannerlinsley,

Excited about the upcoming "Render" and "Viewport Visibility" preloading strategies! Considering their importance, I'd like to request early implementation if possible. While I understand there might not be many requests for additional strategies, having more options would offer developers greater flexibility. Could we discuss the possibility of including them in the current version of Router or perhaps the next release?

Thanks for your attention to this!

[mustakimkr]

@tannerlinsley seeking your attention!

[SeanCassiere]

Exploring the possibility of making the router-plugin compatible with more than just vite.

Following up on this comment in a discussion thread, it seems like could be feasible to open up the router-plugin to other build tools.

unplugin.unjs.io would be the dependency for the compatibility layer, letting us write the plugin once, and get the adapters for vite, rollup, webpack, etc.

The unplugin team, also have an example plugin using Babel for AST traversal, which would let us bring the automatic code-splitting feature to the other build tools as well.

[SeanCassiere]

@lachieh very cool!

I'll drop this in the maintainers' channel and get the others' thoughts on it.

[SeanCassiere]

I'll be tackling this during this week. The current plan is to make the migration and support webpack.

Tracking the migration here: #1756

[SeanCassiere]

The TanStack Router plugin has officially been moved over to unplugin.

[lachieh]

Nice! Working great. I've archived/deprecated mine and pointed it to the official version. Thanks for the quick turnaround!
https://www.npmjs.com/package/unplugin-tanstack-router

[SeanCassiere]

@lachieh thanks for the push! Currently, we've got partial rspack support going! Hopefully, will add more as I get more time 😅.