Routing
Routing in a web application is the process that resolves a particular URL path to a rendered page. Catalyst has a pre-built, opinionated routing scheme for all major storefront page types.
BigCommerce products, categories, brands, and web pages each have a URL path value.
These paths can be generated with various patterns, according to your preferences as set in Settings > General > URL Structure. Catalyst’s routing architecture ensures that URLs in the storefront correspond exactly with these paths. A product with the above URL path value of /sample-orbit-terrarium-small/ will be found at the absolute path mystore.com/sample-orbit-terrarium-small/ on a Catalyst storefront.
Routing File Structure
Let’s take a brief tour of the major route files and directories in Catalyst.
As the project utilizes the Next.js App Router, route files are in the app directory. The directories corresponding with URL patterns include:
- admin - A simple route that redirects to the control panel for the BigCommerce store
- api - Contains routes for a few API endpoints, such as those related to customer authentication
- sitemap.xml - Contains the route dedicated to generating the sitemap
- [locale]/maintenance - The page displayed when the storefront is inactive
- [locale]/(default) - A Next.js route group applying to all other storefront pages. The
(default)directory name is not included as a segment of URL paths. Thelayout.tsxfile in this directory contains common layout for all typical pages.
Within [locale]/(default), there are other noteworthy route groups:
- (auth) - A group including all routes for customer registration, login, and password reset
- (faceted)- A group including all routes that involve product list facet filtering, along with the Server Components and logic common to all of them
The major storefront routes and their file locations with app/[locale]/(default) include:
- page.tsx - Home page
- (auth)/login/page.tsx - Login page
- (auth)/register/page.tsx - Register page
- (faceted)/category/[slug]/page.tsx - Category page
- (faceted)/brand/[slug]/page.tsx - Brand page
- (faceted)/search/page.tsx - Search results page
- product/[slug]/page.tsx - Product detail page
- cart/page.tsx - Cart page
- account/* - Pages within the customer account section
- webpages/normal/[id]/page.tsx - Standard web pages
- webpages/contact/[id]/page.tsx - Contact Us web page
Custom URL Middleware
Next.js Middleware can intercept requests before they reach a specific route, modifying or redirecting them. The central middleware entry point - middleware.ts - loads and executes multiple middleware functions, but the most important to familiarize yourself with is the middleware related to custom URLs.
Note the pattern of the file paths for most of the routes as examined above, which include fixed URL segments like product and dynamic segments like [slug] or [page]. If you review the logic in, for example, the product detail page route file, you’ll see that [slug] is actually expected to be the numerical ID of a product.
This means the route would actually correspond with a URL like this:
mystore.com/product/123
This does not match the expected URL paths of products, categories, etc, that we previously reviewed! We expect URLs like this:
mystore.com/sample-orbit-terrarium-small/
URLs like the latter contain nothing to identify whether they correspond with a product, category, brand or web page. Catalyst utilizes middleware to intercept such requests and determine their final routing.
middlewares/with-routes.ts contains the logic dedicated to this re-routing, which makes an initial GraphQL request to retrieve the type and ID of whatever entity matches the route. This info is then used to rewrite the request URL path, such that Next.js understands the path to be something like the above /product/123 example and directs the request to the final matching route.
KV Storage and Vercel Runtime Cache
The logic described above for determining a dynamic URL path’s final routing involves an extra GraphQL request that must be performed synchronously, before the main data fetching for a given page’s content. It’s also not the only such request; the same middleware also queries for the store status to determine if the maintenance page should be served. These additional round trips to the BigCommerce API have the potential to significantly impact page load times.
To optimize this process, Catalyst employs a key-value (KV) store, or the Vercel Runtime Cache API to cache the results of these route and store status GraphQL requests. In local development environments, the implementation used for this store is a simple JavaScript Map that is not persistent. In deployed environments, however, a true storage implementation is expected.
This means that, in practice, only a small fraction of page renders will ever need to make the GraphQL requests for store status and the route information for a particular path.
For builds hosted on Vercel, the use of the Vercel Runtime Cache will be automatic, with no specific configuration required. For other hosting, Catalyst has built-in support for Upstash for Redis, which must be set up and configured in your hosting environment. It’s simple to implement your own adapter in lib/kv for other KV store implementations. The following are important components for the KV store in the application:
- lib/kv/adapters - Contains the built-in adapters. If you examine the adapter files in this directory, you’ll see that they are each an extremely lean implementation of the
KvAdapterinterface. - lib/kv/index.ts - The
createKVAdapterfunction in this file contains the logic for selecting a KV adapter.
