Shadow Routes

[ericchernuka]

Shadow routes refer to routes that another application may own but still exist under the same domain. While migrating our application, we aim for a centralized source of truth for routing. This ensures that even if some routes exist in another app, our TanStack Router app can maintain typesafe routing. However, it's important to note that when navigating to these shadow routes, the router results in an entire document reload instead of just a client-side navigation.

Problem

It's common when building a new application to bridge the old and new apps to move routes incrementally. The router provides type safety around routes it manages. Still, links to the old application must be handled separately with "hacks" to trick the router into doing a full-page reload by treating the routes as external.

Proposal

Introducing a new route builder, createShadowFileRoute, limits the RouteOptions interface to a subset of features to enable type safety of external routed paths.

Goals

1. Seamless Usage: Shadow routes should integrate like regular routes but remain external to the app. When navigated, they will perform a full document reload. Enables leveraging router paradigms for client-side and external navigation to simplify routing for development teams.
2. Configurable Params: Supports existing param parsing (e.g., "/clients/$clientId").
3. Configurable Search Params: Supports existing search params.
4. Nesting Rules:
   • Routes can have shadow route children.
   • Shadow routes can only have shadow route children.
5. Pending Transition: Ability to leverage "pending" transition state in the router while a full reload is occurring to support the indication that a loading state is occurring on Links or in from Router state.
6. Leverage existing behaviour: Recently, reloadDocument was added to all navigation concepts, which could underpin the behaviour when committing to the navigation route.

API Design

Changes

• Introduce file-based routing builder

// File based
const Route = createShadowFileRoute('/clients/$clientId')({
  params: {
    parse: (params) => ({
      clientId: z.number().int().parse(Number(params.id)),
    }),
  },
  validateSearch: (search) =>
    z.object({
      showDeleteDialog: z.boolean().optional(),
    })
    .parse(search),
});

• Introduce a code-based routing builder

const clientsRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: 'clients',
  beforeLoad: authorizeClientAccess
})

const clientsIndexRoute = createRoute({
  getParentRoute: () => clientsRoute,
  path: '/',
  component: ClientIndexList
})

const clientDetailRoute = createShadowRoute({
  getParentRoute: () => clientsRoute,
  path: '$clientId',
  params: {
    parse: (params) => ({
      clientId: z.number().int().parse(Number(params.id)),
    }),
  },
  validateSearch: (search) =>
    z.object({
      showDeleteDialog: z.boolean().optional(),
    })
    .parse(search),
});

const clientNewRoute = createShadowRoute({
  getParentRoute: () => clientsRoute,
  path: 'new',
});

• Navigating to a route marked as a shadow route will perform a document reload
• Navigation blocking should adhere to proceed logic before performing a shadow route navigation

Previously discussed designs

export const Route = createFileRoute('/clients/$clientId')({
  params: {
    parse: (params) => ({
      clientId: z.number().int().parse(Number(params.id)),
    }),
  },
  validateSearch: (search) =>
    z.object({
      showDeleteDialog: z.boolean().optional(),
    })
    .parse(search),
  shadow: true       // <-- Indicates to the router to do a full document reload
});

Route Splitting

Since these would be part of the route manifest, we do not see a reason they should be part of file-splitting behaviour, but a unique prefix may need to be used to skip it.

Unsupported features of Shadow Routes

1. beforeLoad
2. loader
3. from support
4. Route masking

Considerations

• Filename Convention: Consider .shadow.tsx for easier identification and migration.
• Nesting and Search Params: Can routes have nested search params impacting shadow routes?