↩️
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} />;
};