History

The history object manages navigation between locations within an application.

Curi uses Hickory for its history implementation.

You should almost never have to interact directly with Hickory, but you do have to create your own history object for your application and use it when creating the router.

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

Types of History

There are three types of history to choose from; which 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 URLs into location objects. Only the pathname, query (search), and hash segments are used; locations ignore the domain and protocol segments of a URL.

When matching loactions to routes, only the pathname is used.

// 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.