The configuration properties for Hydrogen are located in the
hydrogen.config.ts file at the root of your project.
This guide describes Hydrogen's configuration properties and how to change the location of the configuration file.
Example configurationAnchor link to section titled "Example configuration"
The Hydrogen configuration file contains information that's needed at runtime for routing, connecting to the Storefront API, and many other options. The following example shows a basic Hydrogen configuration file:
Configuration propertiesAnchor link to section titled "Configuration properties"
The following groupings of configuration properties can exist in Hydrogen:
The default behavior of the
log utility maps to the global
console object. However, you can also customize this behavior in the configuration object.
You can pass any method of the
log utility in the
logger object to override the default behavior. The first argument of each log method contains a
request object if the log was called in the same context as a request. The following Boolean options are also available:
Anchor link to section titled "poweredByHeader"
By default, Hydrogen responds with the
x-powered-by: Shopify-Hydrogen header. You can disable this by adding
poweredByHeader: false to your config:
routes property specifies a path to find server components and API handlers. The default value for the
routes property is
/src/routes, but you can specify the value to any path that starts from the project root:
If your app requires a more advanced configuration, then you can provide additional information about routes manually:
Anchor link to section titled "serverAnalyticsConnectors"
Anchor link to section titled "serverErrorPage"
If an unexpected error occurs while rendering a route, then Hydrogen responds with a 500 HTTP error and renders a default error page at
You can define a custom error page with the
serverErrorPage configuration property. The custom error page is passed an
Error property. The following is an example:
session property allows you to configure sessions support in your Hydrogen storefront. For more information about configuring sessions support in Hydrogen storefronts, refer to Session management.
shopify property contains all the information that your app needs to connect to the Storefront API. This configuration is passed automatically to the
ShopifyProvider component in your app.
For advanced use cases, you can provide a function that returns the same properties. For example, this approach is useful when the Storefront API connection varies depending on the domain or a subpath of the URL:
The function is called inside the
ShopifyProvider component in your app. This means that Suspense fallbacks are shown while resolving the configuration if a promise is returned.
Strict mode is enabled by default for all Hydrogen storefronts in development. It includes strict effects, which mounts and unmounts components multiple times to catch potential issues with user or third-party code.
If strict effects cause problems for your app, then you can turn off strict mode.
Changing the configuration file locationAnchor link to section titled "Changing the configuration file location"
If you don't want the Hydrogen configuration file located at the root of your project, then you can provide the new path to the file in the Hydrogen Vite plugin (
Related componentsAnchor link to section titled "Related components"
- Learn about React Server Components, an opinionated data-fetching and rendering workflow for React apps.
- Get familiar with the file-based routing system that Hydrogen uses.
- Learn about the Hydrogen framework's built-in support for session management.
- Learn about the analytics support built into Hydrogen.