History

A router's history object powers navigation behind the scenes. Besides creating the object and passing it the the curi function to create a router, you likely will not directly interact with it.

Curi uses Hickory packages for its history implementations. Hickory is designed with asynchronous navigation in mind. This means that when a user clicks a link, your application can load data for the mastched route before updating the location.

const history = Browser();
const router = curi(history, routes);

Types of History

There are three Hickory packages to choose from for an application. W hich one you use depends on where your application is running.

Browser History

import Browser from "@hickory/browser";
const browserHistory = Browser();

The browser history is used for applications running in a browser.

If you use the browser history, your application should be hosted on a server that can handle dynamic requests. This either means:

  1. A server with real time route matching (like an Express server).
  2. Configuring the server to respond with a fallback page when the request doesn't map to a real file on the server (e.g. with NGINX or Apache).
  3. Using a static file host that can be configured to respond with a fallback page.

Hash History

import Hash from "@hickory/hash";
const hashHistory = Hash();

The hash history is a fallback history for applications running in a browser. It should only be used if you cannot configure the server to respond to requests that don't match files on the server.

Warning:

This should only be used as a last resort. The browser history is almost always a better choice.

In Memory History

import InMemory from "@hickory/in-memory";
const inMemoryHistory = InMemory();

The in memory history is used for applications not running in a browser. For example, the in memory history is used on the server, in a React Native app, and during testing.

Note:

If you are not familiar with how single-page applications interact with a server, this article should help: Single-Page Applications and the Server.

Locations

The history object will map URL strings into location objects. Only the pathname, query (search), and hash components of a URL are used; locations ignore a URL's domain and protocol.

Matching locations to routes only uses the location's pathname.

// https://www.example.com/page?key=value#trending
location = {
  pathname: "/page",
  query: "key=value"
  hash: "trending"
}

Query Objects

The query value of a location is a string by default, but the history object can be configured to automatically parse it into an object.

You can choose whichever query parsing/stringifying package you prefer. Some of the most popular are qs, query-string, and querystring.

import { parse, stringify } from "qs";
import Browser from "@hickory/browser";

const history = Browser({
  query: { parse, stringify }
});

// https://www.example.com/page?key=value#trending
location = {
  pathname: "/page",
  query: { key: "value" }
  hash: "trending"
}

For more details on the history objects and their APIs, please check out the Hickory documentation.