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
src/pages, then the page displays at
The following example shows how each
*.server.jsx file maps to a different page route in the Hydrogen app:
Server components placed in the
src/pages directory receive the following special props that you can use to create custom experiences:
Each page server component receives props, which includes custom versions of
response and any
serverState that you have passed from the client.
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
In addition to the standard methods,
ServerComponentRequest exposes a
cookies helper, which is a simple
Map of cookie values:
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
If you want to modify the full-page cache options, then you can call
cache() on the response object:
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
You can use
response to set headers or status codes using the
If you want to return users to a different URL, then use
response.redirect() in your server components.
redirect function accepts a
location URL and an optional
statusCode, which defaults to
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:
Server state props
In addition to
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
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:
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
After you've installed
@react-pdf/renderer, create a new server component called