Deploying Hydrogen to Netlify

You probably already know that deploying Hydrogen projects using Oxygen is the recommended approach. However, sometimes we just want to deploy a personal project or share a quick demo with a client — without incurring any costs. For that, Netlify is a great free alternative.

In this article, I’ll show you a ready-to-use template to kickstart your project, and how to adapt an existing one to deploy it for free.

Video

If you prefer a step-by-step walkthrough in video format, check it out below:

Ready-to-use template

If you don't have a project yet, I recommend you download this template from GitHub by running this command:

npm create @shopify/hydrogen@latest -- --template https://github.com/netlify/hydrogen-template

Adapting an existing project

Adapting an existing Hydrogen project to deploy it on Netlify for free can be challenging, depending on the size and complexity of your work. But in this article, I’ll share what I did for my own project — and it worked well! I hope it helps you too.

1. Install the Netlify CLI

To build and preview your project locally, you’ll need to install the Netlify CLI. You can do this by running:

npm install -g netlify-cli@latest

2. Modify your build, and preview commands in package.json

    "build": "remix vite:build",
    "preview": "netlify serve",

3. Install the Netlify adapter

There are packages that we need to install to make the Netlify adapter work. You can install them by running:

npm install @netlify/edge-functions@^2.10.0 @netlify/remix-runtime@^2.3.1 @netlify/remix-edge-adapter@^3.4.3

4. Add netlifyPlugin in your vite.config.ts

You need to add the netlifyPlugin to your vite.config.ts file.

import {netlifyPlugin} from '@netlify/remix-edge-adapter/plugin'

export default defineConfig({
    // ... other configs
    plugins: [
        // ... other plugins
        netlifyPlugin()
    ]
})

5. Modify your server.ts

You can't use the functions from @shopify/remix-oxygen in this file.
Instead, you should adapt it to use functions from @netlify/remix-edge-adapter.

If possible, I suggest copying and pasting this file into your project, and then adding any custom logic or dependencies your project requires.

You'll also notice that we're importing createAppLoadContext from ~/lib/context.
I recommend copying and pasting that file as well, although you're free to adapt it to your project’s structure if needed.

6. Create a file called netlify.toml

This file is essential to set the correct build settings for your project.

[build]
command = "npm run build"
publish = "dist/client"

[dev]
command = "npm run dev"

# Set immutable caching for static files, because they have fingerprinted filenames
[[headers]]
for = "/assets/*"
[headers.values]
"Cache-Control" = "public, max-age=31560000, immutable"

7. Push and Deploy Your Project

Push your updates to the repository. Then, go to Netlify and create a new site by selecting an existing project and choosing the branch you want to deploy.

Make sure your environment variables are correctly set. You can configure them by navigating to your project's settings, then selecting:
Build & Deploy > Environment > Environment Variables.

Now you can deploy your Hydrogen project for free using Netlify!

👉 See my Hydrogen project deployed on Netlify here.

FAQ and Troubleshooting

1. I get a 500 error on the /accounts pages. How do I configure real Shopify customer accounts in local dev?

See these Shopify instructions.

2. Static assets not loading in local dev

If your .js and .css files are failing to load in local development (with 404 responses), you may be running into an issue that occurs when netlify dev is run after having run a build (via netlify build, netlify serve, npm run build, or remix vite:build). This is a known issue that Netlify is working on.

To fix this, delete the conflicting built functions before running your dev server:

rm -rf .netlify/edge-functions*
npm run dev

3. shopify hydrogen preview fails with Cannot find module '@shopify/mini-oxygen'

The shopify hydrogen preview command has a misleading name. It previews your site in a local simulation of the Oxygen hosting platform. It therefore isn't compatible with a site intended to be deployed to Netlify.

Instead, use the Netlify CLI (e.g. netlify serve).

If you encounter any issues while deploying your Hydrogen project to Netlify,
I recommend opening an issue in this Netlify repo.

This article is based on the code from that repository, so the maintainers there are likely the best people to help.

If you don’t get a response there, consider reaching out to Netlify support directly.

If you come across a different issue and find a solution, please let me know!
I’d be happy to include it in this document to make it even more helpful.
Thank you!