Deploy a Hydrogen storefront
You can deploy a Hydrogen storefront to most Worker and Node.js runtimes. This guide describes how to deploy a Hydrogen storefront to Oxygen, Netlify, Vercel, Node.js, Docker, and Cloudflare Workers.
Requirements
Anchor link to section titled "Requirements"You're using the most recent version of Hydrogen. The latest release gives you the benefits of performance enhancements, new components, and other best practices.
If you're deploying to a non-Oxygen runtime, then you've retrieved a delegate access token for server requests and stored it in a private variable.
Deploy to Oxygen
Anchor link to section titled "Deploy to Oxygen"Oxygen is Shopify's recommended deployment platform for Hydrogen storefronts. To learn how to deploy a Hydrogen storefront to Oxygen, refer to Getting started with Oxygen.
Deploy to Netlify
Anchor link to section titled "Deploy to Netlify"To learn how to deploy your Hydrogen storefront to Netlify, refer to the Hydrogen on Netlify documentation.
Deploy to Vercel
Anchor link to section titled "Deploy to Vercel"To learn how to deploy your Hydrogen storefront to Vercel Edge Functions, refer to the Vercel Hydrogen template documentation.
Deploy to Node.js
Anchor link to section titled "Deploy to Node.js"By default, Hydrogen targets a Workers runtime like Oxygen. However, you can also deploy your Hydrogen storefront to Node.js, an open-source JavaScript runtime environment.
Hydrogen provides a built-in Node entrypoint which suits basic production use cases. You can run and preview your Hydrogen storefront in Node.js by building your Hydrogen storefront for production and previewing the app locally:
The production version of your app will be running at http://localhost:3000. You can inspect and deploy the compiled version of your Node.js Hydrogen storefront from dist/node
.
Apply extra middleware
Anchor link to section titled "Apply extra middleware"If you're using the default server entry point in the build --target node
script (@shopify/hydrogen/platforms/node
), then the generated server bundle (dist/node/index.js
) consists of a simple Node.js server that uses Connect middleware.
This bundle also exports the createServer
function, which you can call programmatically to apply extra middleware:
Use a different Node.js framework
Anchor link to section titled "Use a different Node.js framework"If you want to use a different Node.js framework like Express or Fastify, then complete the following steps:
Create a new server entry point (for example,
server.js
) and importhydrogenMiddleware
:Use the new file as the entry point for your build command. For example, if the script is located in
<root>/server.js
, then you would run the following command:Preview the server bundle:
Use App.server.jsx
as the server entry point
Anchor link to section titled "Use App.server.jsx as the server entry point"If your server isn't compatible with Connect middleware or you're deploying to a serverless platform, then you can directly use the App.server.jsx
file as the server entry point.
Update the scripts in package.json
to specify your new entry point:
This exposes a handleRequest
function that can be imported in your server or serverless function:
Deploy to Docker
Anchor link to section titled "Deploy to Docker"You can deploy your project to any platform that supports Docker-based hosting, like Google Cloud Run, Fly.io, and Heroku. If you've generated a Node.js server, then you can run it inside a Docker container.
Install Docker.
Add a Docker file to the root of your project:
Run Docker inside your app directory by executing the following commands:
The production version of your app will be running at http://localhost:8080.
Deploy to Cloudflare Workers
Anchor link to section titled "Deploy to Cloudflare Workers"You can deploy your Hydrogen storefront to Cloudflare Workers, a serverless application platform. For the Cloudflare Workers' Cache API to work, you need to meet the following requirements:
- You have a Cloudflare domain. The domain can't be
worker.dev
, because Cloudflare owns this domain. - You have a DNS record for the Cloudflare domain. For example,
A example.dev 192.0.2.1 Proxied
. - You have a worker route that points to the Cloudflare domain.
Create a
wrangler.toml
file in the root of your project.For more information about the configurable properties in the
wrangler.toml
file, refer to Cloudflare's configuration and compatibility dates documentation.Your static files are now uploaded to Workers KV.
Install Cloudflare's KV asset handler:
Create a new Worker entry file (for example,
worker.js
) in your project:Update
package.json
to specify the new Worker entry point. If the entry point is in<root>/worker.js
, then the changes look like the following:Deploy your project with Wrangler:
Avoid rate limiting in production
Anchor link to section titled "Avoid rate limiting in production"If you're deploying to a non-Oxygen runtime, then this is a necessary step to avoid rate-limiting in production. Learn more about why it's required.
Create a delegate access token for the Storefront API.
Store the token in a private environment variable called
PRIVATE_STOREFRONT_API_TOKEN
.In the Hydrogen configuration file, set the private token using the variable
PRIVATE_STOREFRONT_API_TOKEN
.