History managers

Dojo Routing comes with three history managers for managing an application’s navigation state, HashHistory, StateHistory and MemoryHistory. By default the HashHistory is used, however, this can be overridden by passing a different HistoryManager when creating the Router or using registerRouterInjector.

src/main.ts

import Router from '@dojo/framework/routing/Router';
import StateHistory from '@dojo/framework/routing/history/StateHistory';
import routes from './routes';
// creates a router using the default history manager, `HashHistory`
const router = new Router(routes);
// creates a router using the `StateHistory`
const routerWithHistoryOverride = new Router(routes, { HistoryManager: StateHistory });

Or using the registerRouterInjector helper function:

src/main.ts

import Registry from '@dojo/framework/core/Registry';
import { registerRouterInjector } from '@dojo/framework/routing/RouterInjector';
import StateHistory from '@dojo/framework/routing/history/StateHistory';
import routes from './routes';
const registry = new Registry();
// creates and registers a router using the default history manager, `HashHistory`
registerRouterInjector(routes, registry);
// creates and registers a router using the `StateHistory`
registerRouterInjector(routes, registry, { HistoryManager: StateHistory });

HashHistory

HashHistory uses the fragment identifier to process route changes, for example https://foo.com/#home would process the home as the route path. As HashHistory is the default manager, you do not need to import the module.

import { Router } from '@dojo/framework/routing/Router';
const router = new Router(config);

StateHistory

StateHistory uses the browser’s history API, to manage application route changes.

The StateHistory manager will require server-side machinery to enable an application to support refreshing on a route, for example:

1. Re-writing the index.html request to load from the application root.
2. Re-writing requests to load static resources (.js, .css etc) from the application root.

Note: This machinery is included with @dojo/cli-build-app using the --serve option (intended for development only).

import { Router } from '@dojo/framework/routing/Router';
import { StateHistory } from '@dojo/framework/routing/history/StateHistory';
const router = new Router(config, { HistoryManager: StateHistory });

MemoryHistory

The MemoryHistory does not rely on any browser API but keeps its own internal path state. It should not be used in production applications but is useful for testing application routing.

import { Router } from '@dojo/framework/routing/Router';
import { MemoryHistory } from '@dojo/framework/routing/history/MemoryHistory';
const router = new Router(config, { HistoryManager: MemoryHistory });

src/main.tsx

import renderer from '@dojo/framework/core/vdom';
import { tsx } from '@dojo/framework/core/vdom';
import { registerRouterInjector } from '@dojo/framework/routing/RouterInjector';
import routes from './routes';
import App from './App';
const registry = new Registry();
// creates a router with the routes and registers the router with the registry
registerRouterInjector(routes, registry);
const r = renderer(() => <App />);
r.mount({ registry });

These history managers work like adapters, meaning that custom history managers can be implemented by fulfilling the history manager interface.