Pages

The Hydrogen framework includes page server components. This guide describes how page server components receive props.

How pages work

Hydrogen uses file-based routing, and any pages added to the src/pages folder will be automatically registered as routes by the app.

You might want to add a new page and have it display at localhost:3000/test. You can do this by adding a new file to src/pages. For example, if you add test.server.jsx to src/pages, then the page displays at localhost:3000/test.

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

Props

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

Prop Type
request ServerComponentRequest
response ServerComponentResponse

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

Shows a diagram that illustrates how page serve components receive props

request: ServerComponentRequest

You might want to inspect incoming requests for cookies, headers or other signals that might require a unique response.

All server components receive a request prop containing a Hydrogen-specific version of Request.

In addition to the standard methods, ServerComponentRequest exposes a cookies helper, which is a simple Map of cookie values:

response: ServerComponentResponse

You might want to customize the response returned from the Hydrogen server. For example, set a different status code or define custom headers.

All server components receive a response prop containing a Hydrogen-specific version of Response.

response.cache()

If you want to modify the full-page cache options, then you can call cache() on the response object:

response.doNotStream()

By default, Hydrogen streams SSR responses. To customize a response, you need to tell Hydrogen that your server component plans to modify it in some way by calling response.doNotStream():

You can use response to set headers or status codes using the Response API:

response.redirect()

If you want to return users to a different URL, then use response.redirect() in your server components.

The redirect function accepts a location URL and an optional statusCode, which defaults to 307:

response.send()

If you want to return a different response body than React-rendered HTML, then pass the custom body to response.send() and return it from your server component:

Since this code lives inside a server component, you can use useShopQuery to populate your custom responses with Shopify data.

Server state props

In addition to request and response props, any state you manage with setServerState is passed to each of your page server components as props:

Interacting with custom responses on the browser

When you build custom responses, you might want to call them from the browser using fetch. For example, you could check an API endpoint like /api/views.

To call a custom response from the client, you need to tell Hydrogen about the request using a custom accept header value called application/hydrogen. You can combine this header value with any other accept value. This tells Hydrogen to handle the response using a server component rather than attempting to load an asset:

Creative ways to use custom responses

This section provides examples that show some creative ways to use custom responses in your Hydrogen app. Custom responses are React components that you can use to compose complex functionality in a response.

Custom responses provide the following benefits:

  • You don't have to use a custom API function to respond with JSON or another format.
  • You don't need to use another file or a different pattern to respond with something that's not a standard HTML response.
  • You have complete freedom over the response.

Create a custom sitemap

The following example shows how to create a custom sitemap by adding a new server component called pages/sitemap.xml.server.jsx. The custom response object returns the sitemap.

Build a JSON API

In modern app frameworks, it's common to create custom API endpoints in your own framework powered by the hosting platform you're using. In other frameworks, these API endpoints provide helpful ways to handle lazy-loading, Ajax type incremental data, or POST requests to mutate an external data store. For example, you might want to send a POST request to write to a custom data store after submitting a form.

The following example shows how to build a JSON API with custom responses by adding a new server component called /pages/my-products.server.jsx. The custom response object returns the JSON API:

Generate a spreadsheet

You might want to generate a spreadsheet that includes product data from your store.

The following example shows how to generate comma-separated values (CSV) file by adding a new server component called /pages/spreadsheet.csv.server.jsx. The custom response object returns the spreadsheet:

Generate PDFs

You might want to generate brochures for products in a Shopify store.

The following example shows how to generate a downloadable PDF for a product in a store by installing @react-pdf/renderer:

After you've installed @react-pdf/renderer, create a new server component called /pages/brochure.pdf.server.jsx:

Next steps