Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
matchRoutes
✓ import { matchRoutes } from 'react-router-config';
✗ const matchRoutes = require('react-router-config').matchRoutes;
ESM is preferred. CommonJS `require` syntax is older and often problematic in modern React builds.
renderRoutes
✓ import { renderRoutes } from 'react-router-config';
✗ const renderRoutes = require('react-router-config').renderRoutes;
ESM is preferred. This function is essential for rendering the route components based on the static config.
UMD Global
✓ <script src="https://unpkg.com/react-router-config/umd/react-router-config.min.js"></script>
window.ReactRouterConfig.matchRoutes;
For browser-only usage without a module bundler, the UMD build exposes functionality via `window.ReactRouterConfig`.
This example demonstrates how to define a static route configuration using an array of route objects, match a specific URL pathname against these routes using `matchRoutes`, and then render the corresponding component hierarchy using `renderRoutes` within a React Router v5 `BrowserRouter` context. It includes nested routes and passes extra props.
import React from 'react';
import ReactDOM from 'react-dom/client';
import { BrowserRouter, Link } from 'react-router-dom'; // Requires react-router-dom v5.x or lower
import { matchRoutes, renderRoutes } from 'react-router-config';
// Define your React components
const Home = () => <h2>Home Page</h2>;
const Child = ({ route, match }) => (
<div>
<h3>Child Component: {match.params.id}</h3>
<Link to={`${match.url}/grand-child`}>Go to Grand Child</Link>
{/* Recursively render sub-routes */}
{renderRoutes(route.routes, { extraProp: 'passedValue' })}
</div>
);
const GrandChild = () => <h4>Grand Child Component</h4>;
const NotFound = () => <h2>404 Not Found</h2>;
// Define the static route configuration
const routes = [
{
path: '/',
exact: true,
component: Home,
},
{
path: '/child/:id',
component: Child,
routes: [
{
path: '/child/:id/grand-child',
component: GrandChild,
},
],
},
{ // A catch-all route for unmatched paths
component: NotFound,
},
];
// Example usage: matching routes for a specific path
const path = '/child/123';
const branch = matchRoutes(routes, path);
console.log(`Matched routes for ${path}:`, branch.map(b => b.route.path || b.route.component.name));
// The main App component that uses renderRoutes to display the current route
const App = () => (
<BrowserRouter>
<nav>
<Link to="/">Home</Link> | <Link to="/child/456">Child 456</Link> |
<Link to="/child/789/grand-child">Grand Child</Link> |
<Link to="/non-existent">Non-Existent</Link>
</nav>
<hr />
{/* Renders the top-level routes and their nested structures */}
{renderRoutes(routes)}
</BrowserRouter>
);
// Render the application
const root = ReactDOM.createRoot(document.getElementById('root')!);
root.render(
<React.StrictMode>
<App />
</React.StrictMode>
);
Debug
Known issues
breaking`react-router-config` is incompatible with React Router v6 (and later v7) due to fundamental API changes. React Router v6 introduced the `useRoutes` hook and object-based routing directly into its core, deprecating the need for this separate package entirely.fixMigrate to `react-router-dom` v6+ and use the built-in `useRoutes` hook or `<Routes>` component. A codemod is available to help with this transition.
affects: >=6.0.0 (for react-router)
deprecatedThis package is effectively abandoned and unmaintained. Its last version (5.1.1) was published in 2019, predating the significant architectural shifts in React Router v6 and v7.fixAvoid using this package for new projects. For existing projects, plan a migration to `react-router-dom` v6 or later to leverage current features and community support.
affects: All versions
gotchaThe README explicitly states this is "alpha software" and needs more realistic examples for server rendering and pending navigation, indicating it might not be fully production-ready even for its target React Router v4/v5 versions.fixExercise caution and thoroughly test any advanced use cases. Prefer native `react-router` solutions for robust behavior.
affects: All versions
gotchaRoute objects in `react-router-config` only accept the `component` prop for rendering; `render` or `children` render props, which are available in `<Route>` components of React Router v4/v5, are not supported.fixEnsure all route definitions use the `component` prop. For logic that would typically be in `render` or `children`, wrap the component in a higher-order component or use composition.
affects: All versions
gotchaThe `renderRoutes` function expects to be within a `React Router` context (e.g., `<BrowserRouter>`, `<StaticRouter>`). Calling it outside this context will result in an error.fixAlways wrap the component that calls `renderRoutes` (or your entire app) with an appropriate `Router` component from `react-router-dom`.
affects: All versions
Errors
Common errors & fixes
TypeError: Cannot read properties of undefined (reading 'routes')
Attempting to use `react-router-config` (designed for v5) with React Router v6 or later. The underlying route object structure and APIs have changed significantly, making `matchRoutes` and `renderRoutes` unable to parse the new route definitions.
fixUpgrade to React Router v6+ and refactor your routing logic to use the `useRoutes` hook or the `<Routes>` component, which supports object-based route configuration natively.
Error: Invariant failed: You should not use <renderRoutes> outside a <Router>
The `renderRoutes` function, like other React Router components, relies on context provided by a parent `<Router>` component (e.g., `BrowserRouter`, `HashRouter`, `StaticRouter`). If `renderRoutes` is called without being a descendant of such a router, this error occurs.
fixEnsure that the component calling `renderRoutes` is always rendered within a `BrowserRouter`, `HashRouter`, or `StaticRouter` from `react-router-dom`.
ReferenceError: renderRoutes is not defined
This usually indicates an incorrect import statement, such as attempting to use CommonJS `require` in an ESM module context, or vice-versa, or an incorrect destructuring of the import.
fixVerify that your import statement matches your module system (e.g., `import { renderRoutes } from 'react-router-config';` for ESM, or `const { renderRoutes } = require('react-router-config');` for CommonJS). Audit
Dependencies
reactrequiredPeer dependency required for rendering React components.
react-routerrequiredCore peer dependency for React Router v5 functionality, as this package extends its routing capabilities.
react-router-domoptionalTypically used in browser environments alongside react-router to provide DOM-specific bindings like BrowserRouter.