React magic router

react-magic-router is a library designed to simplify and enhance the use of react-router-dom v6. It offers an easy setup process, type safety, and auto-completion for your routes, making your routing configuration clear and maintainable.

Features

• Type Safety: Ensures that your route paths and parameters are type-checked.
• Auto-complete: Provides auto-completion for your route paths.
• Easy Integration: Integrate with your existing routing setup without breaking your code.
• Supports react-router-dom v6: Currently supports react-router-dom v6 with plans to support v5 and v4 very soon

Installation

npm install react-magic-router

Set up

Add type and declare global type

import type { MappedGlobalRouter, RouteObjectMagic } from 'react-magic-router';

const PUBLIC_ROUTES = [
  {
    path: 'forgot-password',
    element: <ForgotPasswordPage />,
    query: 'email'
  },
  {
    path: 'verify-otp',
    element: <VerifyOtpPage />,
    query: 'email&type' // <-- your query 'email,type'
  },
  {
    path: ':id/profile', // <-- your param ':id'
    element: <ProfilePage />,
  }
  // ... other routes
] as const satisfies RouteObjectMagic[]; // <-- Add this

export const routes = [
  {
    path: '/',
    children: [
      {
        path: '/auth',
        element: <PublicLayout />,
        children: PUBLIC_ROUTES,
      },
      // ...other routes
    ],
  },
] as const satisfies RouteObjectMagic[]; // <-- Add this

// This declaration type is required
declare module 'react-magic-router' { 
  type GlobalMagicRouter = MappedGlobalRouter<typeof routes>;
}

-------------- root app ----------------
import { RouterProvider, createBrowserRouter } from 'react-router-dom';
import {routes} from './your-path'

const router = createBrowserRouter(routes); // the same way with you setup react router v6

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <RouterProvider router={router} />
  </React.StrictMode>,
);

Usage

To navigate

import { useMagicRouter } from './path-to-your-hook';

function MyComponent() {
  const { navigate } = useMagicRouter();
 
  const handleNavigationToVerifyOtp = () => {
    navigate({
      path: '/auth/verify-otp', // <-- this will show autocomplete path for you choose
      query: { email: '[email protected]',type:"..." } // <-- this type will take when you define query of path '/auth/verify-otp' is 'email&type' parse to { email: string , type: string } type
    });
  };

  const handleNavigationToProfile =(id:string)=>{
    navigate({
      path: '/auth/:id/profile',
      param: {
        id
      } // <--- this param will extract form '/auth/:id/profile' parse to { id: string } type
    });
  }

  return (
    <div>
        ...
    </div>
  );
}

To get param

import { useMagicRouter } from './path-to-your-hook';

function MyComponent() {
  const { query } = useMagicRouter('/auth/verify-otp');
  // query will have { email: string , type: string } type

  const { params } = useMagicRouter('/auth/:id/profile');
  // params will have { id: string } type

  return (
    <div>
        ...
    </div>
  );
}

API

import type { RouteObject } from "react-router-dom";

// RouteObjectMagic is extra type of RouteObject
type RouteObjectMagic = {
  children?: RouteObjectMagic[];
  query?: string;
} & DeepReadonly<Omit<RouteObject, "children">>;

// query will is string but this require format 
// query = 'email' -> { email: string}
// query = 'email&otp' -> { email: string , otp: string}
// query = 'email&otp&...' -> { email: string, otp: string, ...}

Limitations

• No JSX Support for Nested Routes: Currently does not support nested routes configured with JSX.
• react-router-dom v5 and v4: Support for these versions is coming soon.

Contributing

Contributions are welcome! Please open an issue or submit a pull request on GitHub.

License

This project is licensed under the MIT License.