README.md

minimal-react-router

minimal-react-router is a lightweight router for React with a small API.

Uses React hooks and requires a peer dependency of react >=16.8.0.

Installation

npm install minimal-react-router

Example

import { createRouter } from "minimal-react-router";

const router = createRouter(window.history, location.href);
const routes = {
  "/one": () => ComponentOne,
  "/two": () => ComponentTwo
};

function App() {
  // Routes are resolved async so the inital value is undefined.
  // Set a default value for the placeholder.
  const [Component = Spinner] = router.useRoutes(routes);
  return <Component />;
}

API

createRouter

router = createRouter(urlHistory, initialURL)

Creates a router instance.

• @param urlHistory History object. Implements pushState and replaceState methods.
• @param initialURL Initial URL string.
• @returns router

router.useRoutes

[
  result,
  {
    parameters: string[],
    path: PathURL {}
  }
] = router.useRoutes(routes)

A custom React hook that takes a routes object and returns a result of the matching route.

• @param routes An object describing the routes.
• @returns [result, { parameters, path }]

router.push

router.push("/new/path")

Navigates to a new path and calls urlHistory.pushState internally. Returns a promise that resolves when all currently loaded routes are resolved.

router.replace

router.replace("/replaced/path")

Replaces the current path and calls urlHistory.replaceState internally. Returns a promise that resolves when all currently loaded routes are resolved.

Objects

Routes object

An object describing the routes.

const routes = {
  "/one": () => ComponentOne,
  "/two": () => ComponentTwo
};

• Route paths must match absolute paths:

"/foo/bar": () => Component

• Route paths cannot contain "?" or "#":

"/foo?param#hash": () => Component // Error!

• If you need to use query params or hashes, use path:

"/foo": ({ path }) => {
  // do something with path.searchParams or path.hash
}

• Route paths can capture path parts:

"/foo/:param/:anotherParam": ({ parameters }) => {
  // path: "/foo/bar/baz" = parameters: ["bar", "baz"]
}

• Route paths support wildcards and match from top down:

"/foo/*/": () => FooSomething,
"/foo/*": () => FooEverythingElse

• Resolvers can be sync or async:

"/home": async () => await isAuthenticated() ? UserHome : Home

• Resolvers can redirect:

"/oldhome": ({ redirect }) => redirect("/home")

• Resolvers have access to the path and params that were used to match:

"/foo/:bar/:baz": ({ parameters, path }) => {
  path.toString() // "/foo/some/thing?q=1#hash"
  parameters // ["some", "thing"]
}

PathURL object

A path object similar to URL but only deals with paths, query parameters, and hashes.

Example:

{
  hash: "#hash",
  pathname: "/foo/bar",
  searchParams: URLSearchParams {},
  ensureFinalSlash: () => "/foo/bar/",

  // Case insensitive, final slash insensitive, compares pathname, query params, and hash.
  matches: (path: string | PathURL) => boolean,
  toString: () => "/foo/bar?queryParam=foo#hash"
}