React Router vs React Router DOM: Core Differences and Usage Scenarios

Overview of the React Router Ecosystem

In React application development, routing management is a crucial component for building single-page applications (SPAs). React Router, as one of the most popular routing solutions, offers a flexible component-based API. However, its ecosystem includes multiple packages, particularly react-router and react-router-dom, which often confuse developers. This article aims to clarify the core differences between these packages and guide their correct usage in various scenarios.

Core Differences Between react-router and react-router-dom

react-router is the foundational package of React Router, containing common components and logic shared across platforms such as web and React Native. These components include Route, Link, Switch, etc., which define basic routing behaviors but do not depend on specific environments like browser DOM or native mobile. Architecturally, react-router implements core routing algorithms, such as path matching and navigation state management, but lacks platform-specific implementations.

In contrast, react-router-dom is a package tailored for the web platform, built on top of react-router and adding browser-specific functionalities. For example, it provides components like BrowserRouter and HashRouter, which internally handle the browser's history API and URL management. Moreover, react-router-dom re-exports all common components from react-router, meaning that in web applications, developers typically only need to import react-router-dom without directly using react-router.

Similarly, for React Native applications, react-router-native should be used, offering native mobile-specific implementations. This design follows the "write once, run anywhere" principle, sharing core logic through the base package while platform packages handle environmental differences.

When to Use react-router or react-router-dom

Based on the above distinctions, the choice of package depends on the target platform:

• For web applications, always use react-router-dom. It includes all necessary routing components and is optimized for the browser environment. For instance, in a React app, one can import as follows: import { BrowserRouter, Route, Link } from 'react-router-dom';. This ensures seamless integration of routing functionality with DOM interactions.
• For React Native applications, use react-router-native, which adapts to native navigation and components.
• Direct usage of react-router is rare, typically only when developers need to build custom routing solutions or cross-platform libraries. In most applications, indirectly using react-router via platform packages is more straightforward.

This layered design enhances code maintainability and reusability, avoiding redundancy in platform-specific code.

Evolution of History Configuration and Best Practices

In earlier versions of React Router (e.g., v3 and before), developers needed to explicitly pass a history object to the Router component, such as: <Router history={browserHistory}>. This allowed custom history management but increased configuration complexity.

Starting with React Router v4, the architecture underwent a significant refactor, introducing a more simplified API. In v4 and later versions, react-router-dom provides built-in components like BrowserRouter and HashRouter, which automatically handle the history object. For example, when using BrowserRouter, there is no need to manually pass history: <BrowserRouter><App /></BrowserRouter>. This simplifies the setup process and reduces errors.

If custom history is still required (e.g., for server-side rendering or testing), one can use the Router component with functions like createBrowserHistory, but this is unnecessary in most web applications. It is recommended to follow official documentation and use platform-specific router components to keep code concise.

Code Examples and Implementation Analysis

To further clarify the concepts, here is a simple web application routing example using react-router-dom:

import React from 'react';
import { BrowserRouter as Router, Route, Link } from 'react-router-dom';

const Home = () => <div>Home Page</div>;
const About = () => <div>About Page</div>;

const App = () => (
  <Router>
    <div>
      <nav>
        <Link to="/">Home</Link>
        <Link to="/about">About</Link>
      </nav>
      <Route exact path="/" component={Home} />
      <Route path="/about" component={About} />
    </div>
  </Router>
);

export default App;

In this example, BrowserRouter (aliased as Router) automatically manages browser history, while Route and Link are from react-router-dom, internally relying on the core functionality of react-router. This demonstrates how to avoid direct usage of react-router in real-world projects.

Summary and Recommendations

In summary, react-router and react-router-dom play different roles in the React Router ecosystem: react-router is the foundational package providing cross-platform shared routing logic; react-router-dom is an extension package for the web, including browser-specific features. When developing web applications, prioritize using react-router-dom, as it simplifies configuration and optimizes performance. For history management, React Router v4 and later versions have automated this process, reducing the need for manual intervention.

Developers should refer to official resources, such as package documentation in the GitHub repository, for the latest information. By understanding these core concepts, one can build more maintainable and scalable React applications effectively.