A router's history enables navigation. It is responsible for creating the location objects, interfacing with its native environment (e.g. a browser) to perform navigation, and telling the router that navigation has occured.
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 matched route before updating the location.
You most likely will not need to interact directly with the application's
history, but you should be familiar with the different choices.
There are three Hickory packages to choose from. Which one you use depends on where your application is running.
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:
- A server with real time route matching (like an Express server).
- 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).
- Using a static file host that can be configured to respond with a fallback page.
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. The browser history is almost always a better choice.
An 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. The
@hickory/in-memory package provides two in-memory history types.
inMemory function is a full history object, capable of in-app navigation, which is useful for native applications and testing.
createReusable function returns lightweight history function for server-side rendering. The returned history cannot navigate, which is fine for server rendering.
The history object will map URL strings into location objects. Only the
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
query value of a location is a string by default, but the history object can be configured to automatically parse it into an object.
A history object has two methods for navigation:
go method allows you to jump to another, already visited.
go takes one argument, the number of locations forward (positive numbers) or backward (negative numbers) to go.
In browsers, there is "external" navigation. This includes the user typing a URL in the address bar and clicking the browser's forward and back buttons. These navigations are all treated similarly to the
There are three types of navigation with
navigate: push, replace, and anchor.
Push navigation adds a new location after the current location. Any locations that existed after the current location are wiped out by push navigation.
Replace navigation replaces the current location with a new location. This has no effect on any locations after the current location.
Anchor navigation is a mix between push and replace. If the new location is the same as the current location, it replaces; otherwise, it pushes. This behavior is the same as how clicking an
<a> in a multi-page application works, hence the name "anchor".
For more details on the history objects and their APIs, please check out the Hickory documentation.