React route manager for react-router

Define and manage application url's in one place.

Getting started

The package is distributed using npm, the node package manager.

npm i --save @lomray/react-route-manager

The TypeScript declarations require TypeScript 5.0 or newer; supported React Router versions are >=6.12.1.

Minimal URL example

Use this when an existing React Router application needs named, typed URL builders. It does not render a router, fetch data, or discover routes from files. Keep your React Router setup; this manager supplies its paths and navigation URLs.

import { Manager } from '@lomray/react-route-manager';

const manager = new Manager({
  routes: {
    users: {
      url: '/users',
      children: {
        detail: { url: '/:id', params: { id: '' } },
      },
    },
  },
});

console.log(manager.path('users.detail')); // ':id' (relative route fragment)
console.log(manager.makeURL('users.detail', { id: 'alice' })); // '/users/alice'

This example is checked with release 2.0.1, React Router 7.9.0 and TypeScript 5.9.2. The declared React Router peer range is not a test matrix. If you change the manager's prefix per request, create a manager per request rather than sharing a mutable instance between requests.

Usage

The examples use React Router 7 or later. With React Router 6, import Link from react-router-dom and RouteObject from react-router instead. The @pages/* modules below are supplied by your application and export route components.

import { Manager } from '@lomray/react-route-manager';
import { Link, type RouteObject } from 'react-router';

/**
 * Application URL manager
 */
const manager = new Manager({
  routes: {
    home: {
      url: '/',
    },
    details: {
      url: '/details',
      children: {
        user: {
          url: '/user/:id',
          params: { id: '' }, // id required param
        },
      },
    },
    about: {
      url: '/about',
    },
  },
});


/**
 * Now we can use it for get routes path for react-router
 */
const routes: RouteObject[] = [
  {
    path: manager.path('home'),
    lazy: () => import('@pages/home'),
  },
  {
    path: manager.path('details'),
    children: [
      {
        index: true,
        lazy: () => import('@pages/details'),
      },
      {
        path: manager.path('details.user'),
        lazy: () => import('@pages/details/user'),
      },
    ],
  },
  {
    path: manager.path('about'),
    lazy: () => import('@pages/about'),
  },
];


/**
 * Also we can use it for generate url's
 */
const MyComponent = () => {
  return (
    <>
      <Link to={manager.makeURL('home')}>Home page</Link>
      <Link to={manager.makeURL('about')}>About page</Link>
      <Link to={manager.makeURL('details')}>Details page</Link>
      <Link to={manager.makeURL('details.user', { id: '1' })}>User page</Link>
    </>
  )
}

Route params

import { Manager } from '@lomray/react-route-manager';

enum DD { First = 'first', Second = 'second' }

const manager = new Manager({
  routes: {
    user: {
      url: '/user/:id/:kind/:status/:name?/:next?/:optionalStatus?',
      params: {
        id: '', // required string
        kind: '' as 'aaa' | 'dddd', // required union
        status: DD, // required enum
        name: undefined, // optional string
        next: undefined as 'aaa' | 'dddd' | undefined, // optional union
        optionalStatus: undefined as DD | undefined, // optional enum
      },
    },
  },
});

manager.makeURL('user', { id: '1', kind: 'aaa', status: DD.First });
// '/user/1/aaa/first'

Required parameters must be supplied, including parameters inherited from parent routes. Routes with only optional parameters can omit the parameter object. Typed route keys support up to 16 segments. Repeated segment names are allowed, and a route with children: {} still has its own key.

Explore demo app to more understand.

Bugs and feature requests

Bug or a feature request, please open a new issue.

License

Made with 💚

Published under MIT License.