Router 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]

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

[tannerlinsley]

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

[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.

[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 😅.

[masoodusmani]

Would love to see parallel routes/named outlets implemented! #605

[tannerlinsley]

Planning it!

[asnaeb]

navigate function in beforeLoad and loader is actually useful. I use it to redirect on unauthorized requests

beforeLoad({navigate}) {
  const client = createClient({
    onRequest() {
      if (auth is expired) {
        navigate({to: "login page"})
      }
    }
  });
  return {client};
}

// Later in some child component

const {client} = Route.useRouteContext();
client.performRequest() // <- Unauthorized request will redirect correctly

throw redirect() doesn't work in such cases as it isn't always thrown inside a loader. Is there any other way to pass the navigate function around that I am not aware of? If not, can we keep it please?

[asnaeb]

I've done it this way initially, it gives me errors when reloading nested routes:
Cannot destructure property '...' of 'Route.useRouteContext(...)' as it is undefined.;

[SeanCassiere]

That shouldn't be happening. Would have to investigated.

Edit: Actually now that I think about it, you don't even need to inject the client into the Router's context, since you are just using the client in the component. You could just directly import it.

[asnaeb]

Well, you are actually right. The reason I wanted to inject it is that vite's fast-refresh doesn't like non-component exports. I guess I will live with the export for now. The error remains tho, should I open an issue with a repro?

[SeanCassiere]

Provided that you are on the latest version, this may be similar to what's described here: #2010

Also, we've got a new routeContext option coming to the route configuration for better stabilization of context and to make it more usable with SSR. Hopefully should ship within the week.
#2104

[asnaeb]

Yes, I'm on the latest version and that is the exact issue.

[BrendanC23]

It would be helpful to add a callback to navigate that would only trigger if the navigation was successful (not blocked by useBlocker). See discussion #271.

[naoya7076]

I’m hoping that typed state on a per-route basis will be introduced in v2.
#284 (reply in thread)

[tannerlinsley]

We could totally do that. Tanner Linsley TanStack LLC

…

On Aug 21, 2024 at 6:20 PM -0600, Naoya Shimizu(Shimmy) ***@***.***>, wrote: I’m hoping that typed state on a per-route basis will be introduced in v2. #284 (reply in thread) — Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you were mentioned.Message ID: ***@***.***>

[jadedevin13]

I'm hoping that production and dev builds are as much as possible behave the same so that no surprises will happen after prod build.

Listing here the relevant issues:

1. Errors from createServerFn is being wrapped and tanstack/query is receiving that error. #2238
2. API Routes support for express handlers #2241
3. server-only Module Causes Build Failure in Development Mode (Inconsistent Behavior Between Development and Production Builds) #1967
4. Calling server function within another server function inside loader alters parameters unexpectedly #1866

[mynk-tmr]

Can you implement the Form component from React router? I think it saves a lot of imperative coding and the pain of forward refs and typing them in TS ?