Routing in PWA Studio

For web applications, routing is the process of mapping a URL to specific page resources.

In a multi-page application, routing is performed on the server side. Every URL request fetches new HTML from the server and the browser loads the entire page. This approach is inefficient because the same assets get loaded every time site navigation occurs.

For a single-page application (SPA), such as a progressive web app, routing is performed on the client side. Single-page applications do not reload the browser during navigation. Instead, the application uses the URL to fetch smaller pieces of data from the server and updates specific items on the page.

Routing for PWA Studio storefronts

PWA Studio provides tools that support both server-side and client-side routing.

Server-side routing

Server-side routing is accomplished using the UPWARD configuration file. Since the configuration file defines how the server responds to requests, you can specify a different template to render each page type, such as a CMS page or a product details page.

Early versions of the Venia storefront used this approach, but in the current version, every page request now returns the same HTML with the application shell. The application decides how the page should render based on the request.

Client-side routing

Client-side routing happens inside the storefront application. When a user navigates inside the application, it updates the relevant pieces instead of refreshing the entire page to update content.

Since Venia is a single-page application, it uses client-side routing for internal navigation.

How routing works in Venia

This section goes over the routing flow implemented in Venia. It is the default workflow for all new projects created using the scaffolding tool, but it is not the only possible workflow for routing.

Initial request

Venia’s UPWARD server handles the initial request to the storefront application. Its upward.yml configuration tells the server to return an index.html page created at build time by Webpack, via the HtmlWebpackPlugin. The content of this file is the same for all page types.

After the browser loads the application shell, routing is handled client-side by React Router.

Routes component

Used inside the App component, the Routes component provides the switch logic for deciding which component to use to render the main content for the current route.

Routes in a PWA do not have to correspond to routes in the old Magento storefront. Venia has routes not defined in the Magento backend, such as Create account or full page Checkout. These routes are assigned components which render content for those pages in the Routes component.

MagentoRoute component

The MagentoRoute component handles the routes that are Magento-specific, such as a product or category page. It uses its Peregrine talon counterpart to determine which component to display.

useMagentoRoute() talon

The useMagentoRoute() talon returns the correct component for a page type. It uses the getRouteComponent() helper function to get the root component associated with a page type. It uses the resolveUnknownRoute() function to determine the page type for a route and retrieves the root component associated with that type using a global fetchRootComponent function. The fetchRootComponent function is autogenerated at build time by the Buildpack RootComponentsPlugin, which searches for RootComponents in the project and builds a manifest.

resolveUnknownRoute()

The resolveUnknownRoute() function is a utility function for fetching page type information from the backend Magento server using a GraphQL query. The getRouteComponent() function uses the information from this query to get the correct root component from an object that maps page types to root components.