React Easy Router

Common errors

• Error: A <Router> is missing a 'router' prop or a 'history' prop. Please render your <Router> in a React app or use a custom router. Learn more: https://reactrouter.com/docs/en/v6/getting-started/tutorial#wrapping-your-app

  cause `react-router-dom`'s `BrowserRouter` component is not wrapping the `react-easy-router`'s `Router` component, which is required since `react-easy-router` v2.0.5.
  fix Wrap your main application component with `<BrowserRouter>` from `react-router-dom`. Example: `<BrowserRouter><App /></BrowserRouter>`

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

  cause The `routes` prop was not passed to the `Router` component, or it was passed as `undefined`.
  fix Ensure you pass a valid array of route objects to the `routes` prop: `<Router routes={myRoutesArray} />`.

• TypeError: Cannot read properties of null (reading 'getItem')

  cause The `isAuthenticated` function or other authentication logic attempts to access browser-specific APIs (like `localStorage` or `window`) in a server-side rendering (SSR) environment without proper checks.
  fix Add checks for `typeof window !== 'undefined'` before accessing browser-only globals within your authentication functions or route elements.

Warnings

• breaking As of v2.0.5, `react-easy-router` no longer internally uses `BrowserRouter`. Your application must now explicitly wrap its root component in `BrowserRouter` from `react-router-dom`.
  Fix: Ensure your main application component, where `Router` is used, is rendered within `<BrowserRouter>` from 'react-router-dom'.
• breaking Since v2.0.2, `react-router-dom` (specifically version >=6.4.0) is a mandatory peer dependency. It must be installed in your project for `react-easy-router` to function.
  Fix: Install `react-router-dom`: `npm install react-router-dom@^6.4.0` or `yarn add react-router-dom@^6.4.0`.
• gotcha The `isAuthenticated` prop expects a function that returns an object like `{ success: true, role: 'yourRole' }` for success, or `false` for failure. Any other return type (e.g., `undefined` or an empty object) might lead to unexpected authentication behavior.
  Fix: Ensure your `isAuthenticated` function explicitly returns `false` or the specified success object structure.
• gotcha A bug in versions prior to v2.1.1 caused all props to be treated as required, even if marked optional. This could lead to validation errors during development.
  Fix: Update to `react-easy-router` version 2.1.1 or later to resolve issues with optional props being enforced.

Install

• npm install react-easy-router npm
• yarn add react-easy-router yarn
• pnpm add react-easy-router pnpm

Imports

• Router
  wrong:

  const Router = require('react-easy-router');

  correct:

  import Router from 'react-easy-router';

  This is the default export of the library, primarily used as a component. CommonJS `require` is not supported for v2+ as the package converted to TypeScript and ESM-compatible architecture.
• RouteObject

  import type { RouteObject } from 'react-easy-router';

  Type import for defining the structure of individual route objects when using TypeScript.
• AuthFunction

  import type { AuthFunction } from 'react-easy-router';

  Type import for the `isAuthenticated` prop function's signature when using TypeScript.

Quickstart

Demonstrates basic usage of `react-easy-router` with a defined array of routes, including nested, dynamic, and protected routes with role-based authentication. It also correctly wraps the application in `BrowserRouter` as required.

import React from 'react';
import ReactDOM from 'react-dom/client';
import { BrowserRouter } from 'react-router-dom';
import Router from 'react-easy-router';

// Placeholder components
const Login = () => <div>Login Page</div>;
const Admins = () => <div>Admins Dashboard</div>;
const Admin = () => <div>Admin Detail</div>;
const Users = () => <div>Users List</div>;
const User = () => <div>User Detail</div>;
const NotFound = () => <div>404 - Page Not Found</div>;

const routes = [
  { path: '/', navigate: '/login' },
  { path: '/login', element: <Login /> },
  {
    path: '/admins',
    element: <Admins />,
    children: [{ path: '/admin', element: <Admin /> }],
  },
  {
    path: '/users',
    element: <Users />,
    children: [{ path: '/user', element: <User /> }],
  },
  {
    path: '/admin',
    element: <Admin />,
    protected: true,
    roles: ['admin', 'manager'], // Optional: Role specific screen
    failureRedirect: '/login', // Optional: Default is '/' if not specified
  },
  { path: '*', element: <NotFound /> },
];

function App() {
  // Function can resolve/reject or return true/false
  const checkAuth = () => {
    const token = typeof window !== 'undefined' ? localStorage.getItem('token') : null;

    // Simulate authentication based on a token and return a role
    if (token === 'admin-token') {
      return { success: true, role: 'admin' };
    } else if (token === 'manager-token') {
      return { success: true, role: 'manager' };
    } else {
      return false; // Not authenticated or no valid token
    }
  };

  return <Router routes={routes} isAuthenticated={checkAuth} />;
}

// Render the app
const root = ReactDOM.createRoot(document.getElementById('root') as HTMLElement);
root.render(
  <React.StrictMode>
    <BrowserRouter>
      <App />
    </BrowserRouter>
  </React.StrictMode>
);