Context and Problem Statement¶

As we develop the Newgotiate UI application, we need to implement client-side routing to navigate between different views and components. We need to select a routing library that is reliable, performant, and aligns with our development practices.

Which routing library should we use for our React application: React Router or TanStack Router?

Decision Drivers¶

• Developer experience and familiarity
• Type safety and TypeScript integration
• Performance characteristics
• Community support and documentation
• Maintenance and future-proofing
• Integration with our existing state management solution
• Ability to handle complex routing scenarios (nested routes, protected routes, etc.)

Considered Options¶

• React Router (v6+)
• TanStack Router (v1)

Decision Outcome¶

Chosen option: TanStack Router

We have decided to use TanStack Router for the Newgotiate UI application due to its superior type safety, file-based routing approach, and seamless integration with our data fetching strategy.

Reasoning¶

1. Type Safety: As we're building a complex application with TypeScript, TanStack Router's first-class TypeScript support provides significant advantages in catching routing-related bugs at compile time rather than runtime.

2. File-Based Routing: The file-based routing approach simplifies route management and provides a clear, intuitive structure that aligns with modern frontend development practices.

3. Integration with TanStack Query: Our application relies heavily on data fetching, and TanStack Router's integration with TanStack Query provides a cohesive solution for managing both routing and data dependencies.

4. Developer Experience: The automatic route type generation and built-in search params validation reduce boilerplate code and improve developer productivity.

5. Future-Proofing: TanStack Router's modern architecture and active development make it a forward-looking choice that aligns with the direction of the React ecosystem.

Implementation Notes¶

• Routes are defined in the src/routes directory
• The routeTree.gen.ts file is automatically generated based on the route files
• We've implemented a singleton router pattern to avoid duplicate router instances
• Route components are loaded lazily to optimize initial load performance

Consequences¶

• Team members will need to learn TanStack Router, which may have a steeper learning curve compared to React Router
• We'll need to create comprehensive documentation and examples to facilitate onboarding
• We may encounter fewer community resources and examples compared to more established routing libraries

Pros and Cons of the Options¶

React Router (v6+)¶

React Router is the most widely used routing library for React applications.

• Good, because it has a large, established community and extensive documentation
• Good, because it's been battle-tested in production across thousands of applications
• Good, because it provides a declarative API that aligns well with React's component model
• Good, because it supports code-splitting and lazy loading out of the box
• Good, because it has built-in support for nested routes and layouts
• Good, because the v6+ version has improved TypeScript support
• Bad, because it can be verbose for complex routing scenarios
• Bad, because some TypeScript integrations still require manual type assertions
• Bad, because it doesn't have built-in data fetching capabilities (though this can be seen as adhering to single responsibility)

TanStack Router (v1)¶

TanStack Router is a newer, type-safe router built by the creator of React Query.

• Good, because it's built with TypeScript from the ground up, offering excellent type safety
• Good, because it integrates seamlessly with TanStack Query for data fetching
• Good, because it provides automatic route type generation
• Good, because it has built-in search params validation and transformation
• Good, because it offers file-based routing similar to Next.js
• Good, because it has a modern, hooks-based API
• Bad, because it's relatively new and has a smaller community
• Bad, because it has fewer learning resources and examples
• Bad, because it may require a steeper learning curve for developers familiar with React Router
• Bad, because it may introduce unnecessary complexity for simpler applications

Suggestions¶

Based on the analysis, here are some suggestions for consideration:

1. If the team is already familiar with React Router and the application doesn't have complex routing needs, React Router would be a safe, proven choice.

2. If type safety is a critical concern and the application heavily uses or plans to use TanStack Query for data fetching, TanStack Router could provide better integration and developer experience.

3. Consider the learning curve and onboarding process for new team members when making this decision.

4. Evaluate how each option integrates with other libraries in your tech stack.

5. For a new project with modern TypeScript practices, TanStack Router offers advantages in type safety that may reduce bugs and improve developer experience.

Links¶

• React Router Documentation
• TanStack Router Documentation