Type-safe data key in throw notFound({ data: ... })

[Sheraff]

Current problem

Currently the notFound() function accepts a params object with the shape of NotFoundError that is then passed as props to the notFoundComponent.

Arbitrary data can be sent through this mechanism with the data?: any key of NotFoundError, but this any prevents us from creating type-safe "not found" errors.

router/packages/react-router/src/not-found.tsx

Lines 8 to 23 in 2088be2

	export type NotFoundError = {
	/**
	@deprecated
	Use `routeId: rootRouteId` instead
	*/
	global?: boolean
	/**
	@private
	Do not use this. It's used internally to indicate a path matching error
	*/
	_global?: boolean
	data?: any
	throw?: boolean
	routeId?: RouteIds<RegisteredRouter['routeTree']>
	headers?: HeadersInit
	}

Goals

Some applications might need to present a different version of the notFoundComponent depending on how/where/why the notFound error was thrown. We can imagine a few cases:

• "You do not have the permission to view this page, ask your manager to add you to the X team"
• "This resource has been deleted, click here to restore it"
• "The A page does not exist, maybe you were looking for B, C, or D?"

Each of the above examples might require some custom props to function properly, in addition to requiring a way to determine which of these to display (assuming an app that uses all 3).

For this reason, this RFC proposes that we should allow users to type the data key.

Possible solutions

1. We consider that it is not the role of the notFoundComponent to handle this variety of cases, and each route should be responsible for displaying such screens. Users can define their own component and pass props to it, there is no need to complexify the route API.

   // no code sample, this solution changes nothing

2. We allow users to type the data key globally, through interface augmentation. Most apps probably don't need a huge variety of "not found" screens, and so simple patterns, globally declared, are probably enough. For example:

   declare module '@tanstack/react-router' {
     interface NotFoundErrorData {
       data:
         | { type: 'foo', a: number }
         | { type: 'bar', b: string }
     }
   }

3. tanstack/router should be the most type-safe router out there, so we need to strongly type the data key on a per-route basis. This can be done through inferring the data type from the errorComponent props, and enforce those types using the routeId key of the NotFoundError

   throw notFound({
     routeId: '/_layout/foo',
     data: { ... },
     // ^? NotFoundErrorData<RegisteredRouter, '/_layout/foo'>
   })

Considerations

• should we consider backward compatibility? Currently the data key is typed as any, and so changing the type to anything else might cause type errors in some applications. However, all 3 of the solutions proposed above can be implemented with no (or minimal) implications for this.

[Sheraff]

An implementation of Solution 2 is available:

• PR: feat(react-router): add NotFoundErrorData interface for improved type safety #3112
• demo: https://stackblitz.com/edit/tanstack-router-fyrpy35d?file=src%2Froutes%2Findex.tsx