# Hydrogen
Hydrogen is Shopify’s opinionated stack for headless commerce, built on [Remix](https://remix.run). It provides a set of tools, utilities, and best-in-class examples for building dynamic and performant commerce applications.
## Setup
1. Create a new Hydrogen project with your preferred package manager.
1. Import components, hooks, or utilities that you want to use in your app. For more, see the [getting started guide](/docs/custom-storefronts/hydrogen/getting-started).
### Create a new Hydrogen project
```
npm create @shopify/hydrogen@latest
```
```
yarn create @shopify/hydrogen
```
- [Tutorial](/docs/custom-storefronts/hydrogen/getting-started): Getting started with Hydrogen and Oxygen
## Authentication
To make full use of Hydrogen, you need to authenticate with and make requests to the [Storefront API](/docs/api/storefront) and the [Customer Account API](/docs/api/customer). Hydrogen includes full-featured API clients to securely handle API queries and mutations.
You can create access tokens for your own Shopify store by [installing the Hydrogen sales channel](https://apps.shopify.com/hydrogen), which includes built-in support for Oxygen, Shopify’s global edge hosting platform. Or install the [Headless sales channel](https://apps.shopify.com/headless) to host your Hydrogen app anywhere.
Both the Storefront API and Customer Account API offer public credentials for client-side applications.
### Authenticate a Hydrogen app
```javascript
/**
* server.js
* ---------
* Create a storefront client.
* Check the server.js file in the root of your new Hydrogen project to see
* an example implementation of this function. If you start from an official
* Hydrogen template (Hello World or Demo Store), then the client is already
* set up for you. Update the Shopify store domain and API token to start
* querying your own store inventory.
*/
const {storefront} = createStorefrontClient({
cache,
waitUntil,
i18n: {language: 'EN', country: 'US'},
// `env` provides access to runtime data, including environment variables
publicStorefrontToken: env.PUBLIC_STOREFRONT_API_TOKEN,
privateStorefrontToken: env.PRIVATE_STOREFRONT_API_TOKEN,
storeDomain: env.PUBLIC_STORE_DOMAIN,
storefrontId: env.PUBLIC_STOREFRONT_ID,
storefrontHeaders: getStorefrontHeaders(request),
});
```
```
# These API credentials fetch example inventory from the Hydrogen Demo Store
# https://hydrogen.shop
#
# Replace with your own store domain and Storefront API token
SESSION_SECRET="foobar"
PUBLIC_STOREFRONT_API_TOKEN="3b580e70970c4528da70c98e097c2fa0"
PUBLIC_STORE_DOMAIN="hydrogen-preview.myshopify.com"
```
- [Install](https://apps.shopify.com/hydrogen): Hydrogen sales channel
- [Install](https://apps.shopify.com/headless): Headless sales channel
## Versioning
Hydrogen is tied to specific versions of the [Storefront API](/api/storefront), which is versioned quarterly. For example, if you're using Storefront API version `2023-10`, then Hydrogen versions `2023.10.x` are fully compatible.
> Caution:
>If a Storefront API version includes breaking changes, then the corresponding Hydrogen version will include the same breaking changes.
- [Learn more](/docs/api/usage/versioning): Shopify API versioning
- [Learn more](/docs/api/release-notes): API release notes
## How Hydrogen works with Hydrogen React
Hydrogen is [built on Remix](/docs/custom-storefronts/hydrogen/project-structure). But many of the components, hooks and utilities built into Hydrogen come from [Hydrogen React](/docs/api/hydrogen-react), an underlying package that’s framework-agnostic. For convenience, the Hydrogen package re-exports those resources. This means that if you’re building a Hydrogen app, then you should import modules from the `@shopify/hydrogen` package.
### Importing Hydrogen components
```jsx
import {ShopPayButton} from '@shopify/hydrogen';
export function renderShopPayButton({variantId, storeDomain}) {
return <ShopPayButton variantIds={[variantId]} storeDomain={storeDomain} />;
}
```
## Resources
## References
- [CacheCustom](https://shopify.dev/docs/api/hydrogen/2023-04/utilities/cachecustom.txt): This allows you to create your own caching strategy, using any of the options available in a `CachingStrategy` object. Learn more about [data fetching in Hydrogen](/docs/custom-storefronts/hydrogen/data-fetching/fetch-data).
- [CacheLong](https://shopify.dev/docs/api/hydrogen/2023-04/utilities/cachelong.txt): The `CacheLong` strategy instructs caches to store data for 1 hour, and `staleWhileRevalidate` data for an additional 23 hours. Note: these time values are subject to change. Learn more about [data fetching in Hydrogen](/docs/custom-storefronts/hydrogen/data-fetching/fetch-data).
- [CacheNone](https://shopify.dev/docs/api/hydrogen/2023-04/utilities/cachenone.txt): The CacheNone() strategy instructs caches not to store any data. The function accepts no arguments. Learn more about [data fetching in Hydrogen](/docs/custom-storefronts/hydrogen/data-fetching/fetch-data).
- [CacheShort](https://shopify.dev/docs/api/hydrogen/2023-04/utilities/cacheshort.txt): The `CacheShort` strategy instructs caches to store data for 1 second, and `staleWhileRevalidate` data for an additional 9 seconds. Note: these time values are subject to change. Learn more about [data fetching in Hydrogen](/docs/custom-storefronts/hydrogen/data-fetching/fetch-data).
- [InMemoryCache](https://shopify.dev/docs/api/hydrogen/2023-04/utilities/inmemorycache.txt): > Caution: > This utility should only be used when deploying Hydrogen to a Node.js environment. It should *not* be used when deploying Hydrogen to Oxygen. If you are deploying Hydrogen to a Node.js environment, you can use this limited implementation of an in-memory cache. It only supports the `cache-control` header. It does NOT support `age` or `expires` headers. Learn more about [data fetching in Hydrogen](/docs/custom-storefronts/hydrogen/data-fetching/fetch-data).
- [generateCacheControlHeader](https://shopify.dev/docs/api/hydrogen/2023-04/utilities/generatecachecontrolheader.txt): This utility function accepts a `CachingStrategy` object and returns a string with the corresponding `cache-control` header. Learn more about [data fetching in Hydrogen](/docs/custom-storefronts/hydrogen/data-fetching/fetch-data).
- [createStorefrontClient](https://shopify.dev/docs/api/hydrogen/2023-04/utilities/createstorefrontclient.txt): This function extends `createStorefrontClient` from [Hydrogen React](/docs/api/hydrogen-react/2023-04/utilities/createstorefrontclient). The additional arguments enable internationalization (i18n), caching, and other features particular to Remix and Oxygen. Learn more about [data fetching in Hydrogen](/docs/custom-storefronts/hydrogen/data-fetching/fetch-data).
- [Pagination](https://shopify.dev/docs/api/hydrogen/2023-04/components/pagination.txt): > Caution: > This component is in an unstable pre-release state and may have breaking changes in a future release. The [Storefront API uses cursors](https://shopify.dev/docs/api/usage/pagination-graphql) to paginate through lists of data and the `` component makes it easy to paginate data from the Storefront API. It is important for pagination state to be maintained in the URL, so that the user can navigate to a product and return back to the same scrolled position in a list. It is also important that the list state is shareable via URL. The `` component provides a render prop with properties to load more elements into your list.
- [getPaginationVariables](https://shopify.dev/docs/api/hydrogen/2023-04/utilities/getpaginationvariables.txt): > Caution: > This component is in an unstable pre-release state and may have breaking changes in a future release. The `getPaginationVariables` function is used with the [``](/docs/api/hydrogen/components/pagnination) component to generate the variables needed to fetch paginated data from the Storefront API. The returned variables should be used within your storefront GraphQL query.
- [graphiqlLoader](https://shopify.dev/docs/api/hydrogen/2023-04/utilities/graphiqlloader.txt): This function creates an instance of [GraphiQL](https://graphql.org/swapi-graphql) in your Hydrogen app when running on a development server. This enables you to explore, write, and test GraphQL queries using your store's live data from the Storefront API. You can visit the GraphiQL app at your storefront route /graphiql. Learn more about [using GraphiQL in Hydrogen](/docs/custom-storefronts/hydrogen/data-fetching/graphiql).
- [storefrontRedirect](https://shopify.dev/docs/api/hydrogen/2023-04/utilities/storefrontredirect.txt): Queries the Storefront API to see if there is any redirect [created for the current route](https://help.shopify.com/en/manual/online-store/menus-and-links/url-redirect) and performs it. Otherwise, it returns the response passed in the parameters. Useful for conditionally redirecting after a 404 response.
- [Seo](https://shopify.dev/docs/api/hydrogen/2023-04/components/seo.txt): The `` component renders SEO meta tags in the document `head`. Add the `` to your `root.jsx` before the `` and `` components. SEO metadata is set on a per-route basis using Remix [loader functions](https://remix.run/docs/en/v1/guides/data-loading). Learn more about [how SEO works in Hydrogen](https://shopify.dev/docs/custom-storefronts/hydrogen/seo).
- [createWithCache](https://shopify.dev/docs/api/hydrogen/2023-04/utilities/createwithcache.txt): Creates a utility function that executes an asynchronous operation like `fetch` and caches the result according to the strategy provided. Use this to call any third-party APIs from loaders or actions. By default, it uses the `CacheShort` strategy.
- [Image](https://shopify.dev/docs/api/hydrogen/2023-04/components/image.txt): The `Image` component renders an image for the Storefront API's [Image object](https://shopify.dev/api/storefront/reference/common-objects/image) by using the `data` prop. You can [customize this component](https://shopify.dev/api/hydrogen/components#customizing-hydrogen-components) using passthrough props. Images default to being responsive automativally (`width: 100%, height: auto`), and expect an `aspectRatio` prop, which ensures your image doesn't create any layout shift. For fixed-size images, you can set `width` to an exact value, and a `srcSet` with 1x, 2x, and 3x DPI variants will automatically be generated for you.
- [ExternalVideo](https://shopify.dev/docs/api/hydrogen/2023-04/components/externalvideo.txt): The `ExternalVideo` component renders an embedded video for the Storefront API's [ExternalVideo object](https://shopify.dev/api/storefront/reference/products/externalvideo).
- [MediaFile](https://shopify.dev/docs/api/hydrogen/2023-04/components/mediafile.txt): The `MediaFile` component renders the media for the Storefront API's [Media object](https://shopify.dev/api/storefront/reference/products/media). It renders an `Image`, `Video`, an `ExternalVideo`, or a `ModelViewer` depending on the `__typename` of the `data` prop.
- [Money](https://shopify.dev/docs/api/hydrogen/2023-04/components/money.txt): The `Money` component renders a string of the Storefront API's[MoneyV2 object](https://shopify.dev/api/storefront/reference/common-objects/moneyv2) according to the `locale` in the [`ShopifyProvider` component](/api/hydrogen/components/global/shopifyprovider). The component outputs a `
`. You can [customize this component](https://api/hydrogen/components#customizing-hydrogen-components) using passthrough props.
- [ModelViewer](https://shopify.dev/docs/api/hydrogen/2023-04/components/modelviewer.txt): The `ModelViewer` component renders a 3D model (with the `model-viewer` custom element) for the Storefront API's [Model3d object](https://shopify.dev/api/storefront/reference/products/model3d). The `model-viewer` custom element is lazily downloaded through a dynamically-injected `