@kalamazoo/router
TypeScript icon, indicating that this package has built-in type declarations

1.0.2 • Public • Published

SPA Router ↩️

The SPA router manages routing with a safe defensive API that unlocks performant SSR and hooks support.

The router is driven by configuration and a pattern called route resources.

More information:

Configuring the router

A basic implementation of the router is not too far removed from other popular router libraries.

// entry.js

import { getTenantContext } from 'common/utils';
import { Router, createHistory } from '@kalamazoo/router';

import { App } from 'spa';
import { routes } from 'spa/routes';

const tenantContext = getTenantContext();
const appRoutes = routes(tenantContext.baseUrl);
const resourceContext = { tenantContext };
const history = createHistory();

// Use this client side, it listens to history changes
export const AppRouter = () => (
  <Router
    routes={appRoutes}
    history={history}
    resourceContext={resourceContext}
  >
    <App />     
  </Router>
);

Routes

Route configuration should be familiar if you have used react-router. There are only a few "required" properties, along with a number of optional properties.

At the minimum, a working route should include the following properties:

Property type Description
path string The path that will be matched for this route to render. The path can contain params which will be provided to the component on match
component ComponentType<RouteContext> The component that will be rendered if the current location matches the path.
resources (optional) RouteResource[] The resources that will be loaded for this route
const routes = [
  {
    path: `/projects/:projectKey`, // `projectKey` will be provided as `this.props.match.params.projectKey` to the component
    component: ProjectsDirectory,
    resources: [projectsDirectoryResource],
  },
];

RouteContext

These props are passed to the component that renders on a matched route.

type RouteContext = {|
  location: Location,
  query: Query,
  route: Route | null,
  match: Match,
  action: HistoryAction,
|};

What are route resources?

Route resources are configuation objects that are used by the router to retrieve, cache, and provide data to the routes.

Creating resources

Resources should always be created using the createResource helper function.

createResource takes in a configuration object that should contain the following properties.

Property type Description
type string Used as a namespace within the router store for this resource. For example a namespace for the boards resource would be 'boards'
getKey (routerStoreContext, resourceStoreContext) => string This function is passed a RouterStoreContext and ResourceStoreContext and is used to identify this resource within the type namespace. For example for a boards you can simply return routerStoreContext.match.params.boardId here
getData (routerStoreContext, resourceStoreContext) => Promise<any> This function is used to load the data for the resource. The function should return a promise and resolve with the resource data object. NOTE: You may not use getData and getDataLoader on the same resource
maxAge number How long (in milliseconds) the resource should be kept in the router before a fresh resource is retrieved. Note: Resources are only refreshed on route change. The router does not poll or update resources in the background. Navigation within the same route, e.g. query param change, will not trigger a refresh of resources.
getDataLoader () => Promise<{default: getData}> Optional property that enables neater code splitting. See more below. NOTE: You may not use getData and getDataLoader on the same resource

Code splitting

Code that is used to retrieve data can be asynchronously imported using the getDataLoader resource property.

The module that is imported through getDataLoader must export a default property that is the function we use to load data.

It is worth noting that you cannot have both getData and getDataLoader on the same resource.

Examples

Example of using createResource using getData:

import { createResource } from '@kalamazoo/router';
import { ROUTE_RESOURCE_TYPE_DIRECTORIES_PROJECTS } from 'spa/routes/resources';
import { getProjectsDirectoryData } from 'spa-apps/projects-directory';

export const projectsDirectoryResource = createResource({
  type: ROUTE_RESOURCE_TYPE_DIRECTORIES_PROJECTS,
  getKey: (routerContext, resourceContext) => {
    const { match } = routerContext;
    const { tenantContext } = resourceContext;

    return match.params.id;
  },
  getData: async (routerContext, resourceContext) => {
    const { query } = routerContext;

    // Tenant context is always provided in the Jira SPA
    const {
      tenantContext: { baseUrl, isAdmin },
    } = resourceContext;

    return getProjectsDirectoryData(baseUrl, isAdmin, query);
  },
  maxAge: 30 * 1000,
});

Example of using createResource using getDataLoader:

// data-loader.js

const loadMyData = async (routerContext, resourceContext) => {
  const { query } = routerContext;

  // Tenant context is always provided in the Jira SPA
  const {
    tenantContext: { baseUrl, isAdmin },
  } = resourceContext;

  return getProjectsDirectoryData(baseUrl, isAdmin, query);
};

export default loadMyData;

// resource.js

import { createResource } from '@kalamazoo/router';
import { ROUTE_RESOURCE_TYPE_DIRECTORIES_PROJECTS } from 'spa/routes/resources';
import { getProjectsDirectoryData } from 'spa-apps/projects-directory';

export const projectsDirectoryResource = createResource({
  type: ROUTE_RESOURCE_TYPE_DIRECTORIES_PROJECTS,
  getKey: (routerContext, resourceContext) => {
    const { match } = routerContext;
    const { tenantContext } = resourceContext;

    return match.params.id;
  },
  getDataLoader: () =>
    import(/* webpackChunkName: "async-projects-directory" */ './data-loader'),
  maxAge: 30 * 1000,
});

Router configuration

Basic configuration

// entry.js

import { getTenantContext } from 'common/utils';
import { Router, createHistory } from '@kalamazoo/router';

import { App } from 'spa';
import { routes } from 'spa/routes';

const tenantContext = getTenantContext();
const appRoutes = routes(tenantContext.baseUrl);
const resourceContext = { tenantContext };
const history = createHistory();

// Use this client side, it listens to history changes
export const AppRouter = () => (
  <Router
    routes={appRoutes}
    history={history}
    resourceContext={resourceContext}
  >
    <App />
  </Router>
);

Accessing router state

You can access the current state of the router using the useRouter hook or the RouterSubscriber component.

Both components provde both routerState for reading the current router state, and routerActions for modifying router state.

import type { Query, Route, Match, HistoryAction } from '@kalamazoo/router';

type RouterState = {
  location: Location,
  query: Query,
  route: Route,
  match: Match,
  action: HistoryAction,
};

type RouterActions = {|
  push: (path: Href | LocationShape, state?: any) => RouterAction,
  replace: (path: Href | LocationShape, state?: any) => RouterAction,
  goBack: () => RouterAction,
  goForward: () => RouterAction,
  registerBlock: (blocker: HistoryBlocker | any) => RouterAction,
|};

RouterSubscriber component

import { RouterSubscriber } from '@kalamazoo/router';

import { MyComponent } from 'my-component';

export const MyRouteComponent = () => (
  <RouterSubscriber>
    {(routerState, routerActions) => (
      <MyComponent location={routerState.location} push={routerActions.push} />
    )}
  </RouterSubscriber>
);

useRouter hook

import { useRouter, RouterSubscriber, withRouter } from '@kalamazoo/router';

export const MyRouteComponent = () => {
  const [routerState, routerActions] = useRouter();

  return (
    <MyComponent location={routerState.location} push={routerActions.push} />
  );
};

withRouter HoC

The withRouter HoC can be used for decorating your component. It provides the following props to its children.

Prop Type
location Location
query Query
route Route
match Match
action HistoryAction
history BrowserHistory
import { withRouter } from '@kalamazoo/router';

export const WithRouterHocExample = withRouter(MyComponent);

const MyRouterComponent = () => {
  return <WithRouterHocExample />;
};

Router Actions

Router Actions can be accessed through a dedicated hook or a dedicated subscriber.

Both the component and the hook have been optimised so that they will not re-render on URL change.

type RouterActionsType = {
  push: (path: Href | Location, state?: any) => any,
  replace: (path: Href | Location, state?: any) => any,
  goBack: () => any,
  goForward: () => any,
  registerBlock: (blocker: Function) => () => void,
};

Router Actions hook

Router actions can be accessed through a hook.

import { useRouter, RouterActions, withRouter } from '@kalamazoo/router';
import { Href } from '@kalamazoo/router';
import { MyComponent } from 'my-component';

export const HooksExample = () => {
  const {
    push,
    replace,
    goBack,
    goForward,
    registerBlock,
  } = useRouterActions();

  return <MyComponent push={push} />;
};

Router Actions subscriber

This component has been optimised so that it will not re-render on URL change.

export const RenderPropsExample = () => (
  <RouterActions>
    {routerActions => <MyComponent push={routerActions.push} />}
  </RouterActions>
);

Link

import { Link } from '@kalamazoo/router';

export const LinkExample = ({ href = '/' }) => {
  const handleClick = () => console.log('click');

  return (
    <Link href={href} onClick={handleClick}>
      Link Component
    </Link>
  );
};

Redirect

import { Redirect, useResource } from '@kalamazoo/router';
import { userResource } from 'spa/routes/resources';
import { Profile } from 'spa/user';

export const RedirectExample = () => {
  const [{ data, loading, error }] = useResource(userResource);

  if (loading) {
    return <div>Loading...</div>;
  }

  if (error && error.code === 403) {
    return <Redirect to="/login" />;
  }

  return <Profile data={data} />;
};

Readme

Keywords

Package Sidebar

Install

npm i @kalamazoo/router

Weekly Downloads

0

Version

1.0.2

License

Apache-2.0

Unpacked Size

388 kB

Total Files

265

Last publish

Collaborators

  • stevenselcuk