React Router v5 Compatibility Layer

Common errors

• Error: Invalid hook call. Hooks can only be called inside of the body of a function component.

  cause Attempting to use `useCompatHistory` or other `useCompat` hooks outside of a component rendered within a `CompatRouter` context.
  fix Ensure that any component using `useCompatHistory` or similar compatibility hooks is a child of `CompatRouter` (or `BrowserRouter as CompatRouter`).

• Error: No routes matched location "/path"

  cause This often indicates a mismatch between v5 and v6 routing configurations. For example, a v5 `CompatRoute` inside a v6 `Routes` without being nested in a `CompatSwitch` or `CompatRouter` that interprets v5 routes.
  fix Verify that v5 compatibility routes are correctly nested within `CompatRouter` and `CompatSwitch` components, and that the `path` props align with v5's exact/non-exact matching rules.

• TypeError: Cannot read properties of undefined (reading 'push')

  cause Likely attempting to access `history.push` from `useCompatHistory` before the history object is properly initialized by the `CompatRouter` or outside its scope.
  fix Confirm that the component calling `useCompatHistory` is rendered within the component tree established by `CompatRouter`.

Warnings

• breaking This package is a temporary migration tool for React Router v6. It is not intended for long-term use and applications should aim for full migration to native React Router v6 (or later v7) constructs to leverage all performance and API benefits.
  Fix: Prioritize refactoring v5-specific routing logic to use native `react-router-dom` v6 or v7 APIs (e.g., `useRoutes`, `useNavigate`, `Routes` component).
• gotcha Mixing `react-router-dom` v5 and v6 contexts and hooks directly can lead to unexpected behavior or runtime errors. Ensure that v5 compatibility components/hooks (e.g., `useCompatHistory`) are only used within a `CompatRouter` context.
  Fix: Always wrap v5-dependent components with `CompatRouter` and use the aliased `Compat` prefixed hooks and components from `react-router-dom-v5-compat` when working with v5 logic.
• deprecated The underlying `react-router-dom` v5 itself is considered deprecated, with `react-router` having moved to v7. While `v5-compat` helps with the v6 transition, new development should target the latest stable version of `react-router-dom`.
  Fix: Plan and execute a complete migration to `react-router-dom` v6 or v7 as soon as feasible. Consult the official React Router migration guides for detailed steps.

Install

• npm install react-router-dom-v5-compat npm
• yarn add react-router-dom-v5-compat yarn
• pnpm add react-router-dom-v5-compat pnpm

Imports

• CompatRouter
  wrong:

  import { CompatRouter } from 'react-router-dom-v5-compat'; // Incorrect alias

  correct:

  import { BrowserRouter as CompatRouter } from 'react-router-dom-v5-compat';

  This package re-exports the v5 `BrowserRouter` as `CompatRouter` to be used within a v6 application. You typically import it as an alias.
• CompatSwitch
  wrong:

  import { CompatSwitch } from 'react-router-dom-v5-compat'; // Incorrect alias

  correct:

  import { Switch as CompatSwitch } from 'react-router-dom-v5-compat';

  Re-exports the v5 `Switch` component, which is crucial for v5 route matching logic. `Switch` was removed in v6.
• useCompatHistory
  wrong:

  import { useHistory } from 'react-router-dom-v5-compat'; // Ambiguous with v6's useNavigate

  correct:

  import { useHistory as useCompatHistory } from 'react-router-dom-v5-compat';

  Re-exports the v5 `useHistory` hook. In v6, `useNavigate` is the successor, so using the aliased `useCompatHistory` makes it clear you're using the v5 equivalent.

Quickstart

Demonstrates how to integrate v5-style components and hooks using `react-router-dom-v5-compat` within a v6 `react-router-dom` application, allowing for a phased migration.

import React from 'react';
import ReactDOM from 'react-dom/client';
import { BrowserRouter as Router, Routes, Route, Link } from 'react-router-dom';
import { BrowserRouter as CompatRouter, Switch as CompatSwitch, useHistory as useCompatHistory } from 'react-router-dom-v5-compat';

// A v5-style component
function OldHomePage() {
  const history = useCompatHistory();
  const handleClick = () => {
    history.push('/old-about');
  };
  return (
    <div>
      <h2>Old Home Page (v5 compat)</h2>
      <button onClick={handleClick}>Go to Old About</button>
      <Link to="/v6-dashboard">Go to v6 Dashboard</Link>
    </div>
  );
}

// Another v5-style component
function OldAboutPage() {
  return <h2>Old About Page (v5 compat)</h2>;
}

// A v6-style component
function V6Dashboard() {
  return <h2>V6 Dashboard</h2>;
}

function App() {
  return (
    <Router>
      <h1>Mixed React Router App</h1>
      <Routes>
        {/* v6 routes */}
        <Route path="/v6-dashboard" element={<V6Dashboard />} />
        <Route path="/" element={
          <CompatRouter>
            {/* v5 compatibility routes inside CompatRouter */}
            <CompatSwitch>
              <CompatRoute path="/old-about" component={OldAboutPage} />
              <CompatRoute path="/" component={OldHomePage} />
            </CompatSwitch>
          </CompatRouter>
        } />
      </Routes>
    </Router>
  );
}

const root = ReactDOM.createRoot(document.getElementById('root'));
root.render(<App />);