Skip to main content

Routing

tip

Hydrogen 2.0 is out now. These archival Hydrogen 1.0 docs are provided only to assist developers during their upgrade process. Please migrate as soon as possible.

The Hydrogen framework uses a file-based routing system. This guide provides an introduction to how routing works in your Hydrogen storefront.

How routes work​

All components added to the src/routes directory are registered as routes in App.server.jsx. Any filenames with brackets, like [handle], are converted to a route parameter called :handle.

You can navigate between routes using the Link component or the useNavigate hook. You can use the useRouteParams hook to retrieve the parameters of an active route.

The following example shows how each *.server.jsx file maps to a different route in the Hydrogen app:

└── src
    ├── routes
        └── collections
            └── [handle].server.jsx // localhost:3000/collections/<handle>
        └── pages
            └── [handle].server.jsx // localhost:3000/pages/<handle>
        └── products
            └── [handle].server.jsx // localhost:3000/products/<handle>
        └── index.server.jsx // localhost:3000/

Example​

You have following components in your src/routes directory:

/routes/index.server.jsx
/routes/custom-page.server.jsx
/routes/products/[handle].server.jsx

The routes are registered in App.server.jsx and Hydrogen converts [handle] to :handle:

/
/custom-page
/products/:handle

Built-in routes​

Hydrogen provides the following built-in routes:

  • /__health: A health check route that responds with a 200 status and no body. You can use this route within your infrastructure to verify that your app is healthy and able to respond to requests.
  • /__rsc: An internal route used to re-render server components. It's called by the Hydrogen frontend when the route changes, or when server props change. You should never need to manually request this route.
  • /__event: An internal route used to save client observability events. You should never need to manually request this route.

Custom routes​

By default, Hydrogen uses a file-based routing system, but you can customize routes in App.server.jsx using the following components:

  • Router: Provides the context for routing in your Hydrogen storefront
  • FileRoutes: Builds a set of default Hydrogen routes based on the output provided by Vite's import.meta.globEager method
  • Route: Used to set up a route in Hydrogen that's independent of the file system

API routes​

API routes allow you to build your API in Hydrogen. Any server component within the src/routes directory that exports an API function will become an API route. The following examples show some common use cases for implementing API routes.

Example​

The following example shows a "Hello world" implementation of an API route:

export function api(request, {params}) {
  return new Response('Hello world!');
}

{% endcodeblock%}

Learn how to work with API routes.

Props for creating custom experiences​

Shows a diagram that illustrates how server components receive props

Server components placed in the src/routes directory receive the following special props that you can use to create custom experiences:

PropType
requestHydrogenRequest
responseHydrogenResponse

Each server component receives props, which includes custom versions of request and response and any serverProps that you have passed from the client.

Learn how to create custom experiences with props.

TypeScript​

Hydrogen supports TypeScript out of the box. When building route components, you can use the provided TypeScript types to improve your developer experience:



import type {
  HydrogenApiRoute,
  HydrogenApiRouteOptions,
  HydrogenRequest,
  HydrogenRouteProps,
} from '@shopify/hydrogen';

export default function MyPage(props: HydrogenRouteProps) {
  //
}

export const api: HydrogenApiRoute = async (request, options) => {
  //
};

// Alternate version of `api`:
export async function api(
  request: HydrogenRequest,
  options: HydrogenApiRouteOptions
) {}

Tip: The Hello World template is available in TypeScript. You can also refer to the example implementation of TypeScript in GitHub.

Next steps​