A single-page application is made up of a number of "routes", which are the valid locations within the application. The router matches the application against its routes to determine which one matches.
A route's name needs to be unique. Route names are used to identify which route to interact with for different functionality, like navigation.
A route's path is what the router uses to identify if a location matches the route. The path is only matched against the location's pathname, the other parts of a URL are not used for matching.
The website will start with four routes.
Lists books available for purchase.
Details about an individual book. The id param identifies a specific book.
Buy the books in the shopping cart.
Display a not found page. This path matches every location (using a regular expression syntax), so it should be the last route.
Inside of the src directory, we will create a routes.js file where we can define the application's routes.
We can create an array of routes using the above names and paths.
@curi/router provides a prepareRoutes function, which is used to setup routes for the router. We will pass the routes array to prepareRoutes and export the result of that function call.
We will be creating the router in the index.js file, so the routes array should be imported there.
The routes define what the application renders for a particular location, but we also need to define how the application navigates. When we create the router, we will pass it a history function that will be used to enable navigation.
Curi uses the Hickory library for its history. There are a few Hickory packages to choose from for different environments. For most websites, the @hickory/browser is the right choice for the front end.
We can import the browser function from @hickory/browser in our index file (src/index.js, which create-react-app created for us).
We are now ready to create the router. In the src/index.js file, we should import the createRouter function from @curi/router. To create the router, call the createRouter function passing it the history function and the routes array.
The router is now ready and we can render the application, but first we should do something really important: make the site more accessible.
In a multi-page application, a screen reader will announce navigation to users. This happens automatically when a new Document is loaded. A single-page application reuses its Document, which is great for removing unnecessary server requests, but also means that the navigation is no longer automatically announced.
Curi has a concept of "side effects". These are functions that are called after a navigation happens and are passed an object with data about the navigation.
The @curi/router package provides a few side effects that are useful for websites. For now, we will focus on the announce side effect. The announce side effect returns a string, which sets the text content of a ARIA Live region. Screen readers will detect the changed text and read it to the users.
Let's go ahead and add the announce side effect to the router. We will have it return a string of the response's pathname.
The @curi/react-dom provides the components that we will use to interact with the router.
We create a Router component by passing the router to the createRouterComponent higher-order component.
The Router component will re-render the application whenever there is in-app navigation. It also sets up a React context, so any @curi/react-dom components and hooks need to be descendants of the Router in order to access the context.
We will pass the Router the App element, which is where we will render the application's content.
The existing content from src/App.js can be removed and we will start from scratch.
We will import the useResponse hook from @curi/react-dom. This hook lets us read the context data that was set by the Router. useResponse returns three objects: router, response, and navigation.
The router property is our Curi router, but what are the other two?
The response is the most useful of these three properties, but the other two may can be handy. For example, the navigation can be useful for animating route transitions.
How do we render using the response? Any way you want! The best way is to use a response's body property.
We can update the App to get the response using useResponse.
If a response's body is a React component, we can render it! We haven't actually defined components for our routes yet, so we should throw together some placeholders.
These components can be imported in src/routes.js. Each route can be given a respond function which returns an object with their respective component as its body.
Now that the responses have body properties that are React components, we can update the App to render them.
We will also pass the response as a prop to the rendered component, which means that each of the route components will have access to the response when they are rendered. This isn't strictly necessary, but can come in handy.
At this point in time our app is rendering, but is isn't very interesting because we cannot navigate between locations.
The website should link to individual books from its home page. To do this, we need data about the available books. Since we don't have a backend to fetch book data from, we'll hard-code the books data in the src/books.js module.
You can copy+paste or modify the data, but the structure of the provided data should stay the same.
The data can be imported in the Home component and we can iterate over the books to render a Link to each one.
Now that we can navigate to the books, we should fill out the UI for the Book component. Up above, we passed the response object as a prop to the response.body component. Now, we can use that object in the Book component to access the captured route params so that we know which book to show.
We will once again import the books.js data. We can use params.id to select the correct book. params.id is a string, so we will need to parse it into an integer. Sometimes there won't be a valid book for the params.id. In that case, we will also want to display a message that the requested book could not be found.
The useRouter hook allows us to access our router from anywhere in our component tree (that is a descendant of the <Router>).
While links are generally the best way to navigate, sometimes an application should navigate as the result of another action. For instance, after a user login is authenticated, the application may redirect to another page.
We will implement something similar in the Book component by having the application navigate to their shopping cart after they add a book to it.
In the Book components module, we should import the useRouter hook from @curi/react-dom as well as our shopping cart API.
Finally, we can update our Checkout component to display the books in the shopping cart. To do this, we will import our cart and books. Our cart only stores book ids, so we will need to merge the book data with the cart data.
When a user "buys" the books in their shopping cart, we need to clear out the cart. We will also replace the current location with one whose location.hash is the string "thanks". When that is present in the location, we can render a "Thanks for your purchase" message instead of the cart's contents. Once again, we will use the useRouter hook to access the router in order to change locations.