Middleware

Catalyst uses Next.js Middleware (opens in a new tab) to support key features in storefront requests.

Middleware in Next.js

Middleware code executes before a route is rendered and provides an entry point for common tasks like logging, authentication, or redirects.

middleware.ts (opens in a new tab) in the storefront root directory is responsible for applying the various middleware used by Catalyst. Each web request is “intercepted” by this middleware, which handles tasks such as managing the customer’s session and rewriting the request URL, before the request is then sent on to its final route.

Any URL patterns for which middleware should not be applied can be configured in the config exported by middleware.ts. By default, static files such as sitemaps and robots.txt are not subject to middleware.

As an example, if you have created a custom route for URLs starting with /product-configure, and these paths don’t need to be subject to any middleware. Updating the config in middleware.ts as follows would exclude them:

export const config = {
	matcher: [
		'/((?!product-configure|api|admin|_next/static|_next/image|_vercel|favicon.ico|xmlsitemap.php|sitemap.xml|robots.txt).*)',
	],
}

With auth

The with-auth middleware is a wrapper over a minimal implementation of Auth.js, formerly NextAuth.js (opens in a new tab). This provides Catalyst with session management for shoppers' carts and customers' logged-in states. By default, it uses JWT cookies to avoid obligatory dependency on any persistence layer on the storefront itself. You may wish to extend this functionality to store more information in a session or add a persistence layer yourself for more flexibility and control over shopper sessions.

With routes

The with-routes middleware overrides the default Next.js file-based routing behavior (opens in a new tab) to provide support for certain BigCommerce features in a way that allows changes users make with the store control panel and APIs to have the expected effect on the storefront.

Let's look at an example. The following is a fairly typical terse, SEO-friendly URL path:

/fancy-high-top

In a hypothetical store, this might correspond with the URL path set on a product. However, the URL path itself does not contain any information to indicate it belongs to a product. And based on the file path of the route at app/[locale]/default/product/[slug]/page.tsx, the URL pattern Next.js actually expects is similar to the following example:

/product/123

Despite the param name [slug], what the route expects in the segment is a product entity ID. The with-routes middleware sends the path /fancy-high-top to BigCommerce using the GraphQL Storefront API's route() node (opens in a new tab) to determine the entity (in this case, a product) that corresponds with the supplied path. It then performs an internal Next.js rewrite to the entity-specific path /product/123, resulting in the page being rendered by the appropriate route.

The net effect is to provide full freedom for the custom URL configuration BigCommerce provides. This allows for any desired URL pattern from /fancy-high-top to /product/fancy-high-top to /shoes/high-tops/fancy-high-top.

This ensures that any URL assigned to an object's node (opens in a new tab) using either the store control panel or APIs works as expected on the Catalyst storefront, including 301 redirects (opens in a new tab).

The with-routes middleware also checks the storefront status (opens in a new tab) so that when a control panel or API user takes a storefront down for MAINTENANCE or sets it to LAUNCHED, the live storefront reflects the change without waiting for a rebuild of the Next.js application.

Performance and KV Store Configuration

Using the with-routes middleware introduces a performance cost, since it requires an additional blocking API request to render site pages.

Although path-to-entity mappings can be cached, Next.js middleware cannot use the built-in Data Cache (opens in a new tab) which is used to cache fetched data in other parts of Catalyst. Instead, a separate caching backend must be used. Catalyst uses a caching implementation (opens in a new tab) that’s flexible for multiple KV adapters.

If your Catalyst storefront does not rely on control panel or API-configured URLs, and you do not need storefront status checks, you can safely remove the with-routes middleware to improve performance.

For projects where URL structures need to be tightly controlled, consider defining routes at build time or implementing custom routing strategies.