Deployment

Hydrogen app

Oxygen

You can use Oxygen to deploy your Hydrogen app for free using the Shopify’s official hosting solution. If you have added the Hydrogen channel to your Shopify store and if you want to deploy your app to Oxygen, read the official Shopify guide.

Vercel

You can use Vercel to deploy your Hydrogen app to their global edge network with zero configuration. This guide includes instructions for deploying to Vercel through the website UI or Vercel’s CLI.

Website UI Deployment

1. Push your code to your online Git repository (GitHub, GitLab, BitBucket).
2. Import your project into Vercel.
3. Vercel will automatically detect Remix and configure the right settings.
4. Copy paste your environment variables.
5. Your application is deployed!

After your project has been imported and deployed, all subsequent pushes to branches will generate Preview Deployments, and all changes made to the Production Branch (commonly “main”) will result in a Production Deployment.

CLI Deployment

1. Install the Vercel CLI and run vercel to deploy.

npm install -g vercel
vercel

2. Vercel will automatically detect Remix and configure the right settings.
3. When asked Want to override the settings? [y/N], choose N.
4. Your application is now deployed, but still need to configure your environment variables using the Vercel website UI.

Troubleshooting

Oxygen deployment

If you try to deploy Fluid to Oxygen using pnpm as a dependency manager, deployment might fail with the following error:

The `npm ci` command can only install with an existing package-lock.json or
npm-shrinkwrap.json with lockfileVersion >= 1. Run an install with npm@5 or
later to generate a package-lock.json file, then try again.

When deploying to Oxygen, Shopify will automatically create a Pull Request with the following Github Action:

# Don't change the line below!
#! oxygen_storefront_id: 1000016008

name: Storefront 1000016008
on: [push]

permissions:
  contents: read
  deployments: write

jobs:
  deploy:
    name: Deploy to Oxygen
    timeout-minutes: 30
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup node.js
        uses: actions/setup-node@v4
        with:
          node-version: "lts/*"
          check-latest: true

      - name: Cache node modules
        id: cache-npm
        uses: actions/cache@v4
        env:
          cache-name: cache-node-modules
        with:
          path: ~/.npm
          key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ hashFiles('**/package-lock.json') }}
          restore-keys: |
            ${{ runner.os }}-build-${{ env.cache-name }}-
            ${{ runner.os }}-build-
            ${{ runner.os }}-

      - name: Install dependencies
        run: npm ci

      - name: Build and Publish to Oxygen
        run: npx shopify hydrogen deploy
        env:
          SHOPIFY_HYDROGEN_DEPLOYMENT_TOKEN: ${{ secrets.OXYGEN_DEPLOYMENT_TOKEN_1000016008 }}

Unfortunately, this Github Action will fail if your repo is using pnpm because it is looking for a package-lock.json lockfile.

To fix this you can update your Github Action as follows (don’t forget to update the Oxygen Storefront ID):

# Don't change the line below!
#! oxygen_storefront_id: 1000016008

name: Storefront 1000016008
on: [push]

permissions:
  contents: read
  deployments: write

jobs:
  deploy:
    name: Deploy to Oxygen
    timeout-minutes: 30
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup node.js
        uses: actions/setup-node@v4
        with:
          node-version: "lts/*"
          check-latest: true

      - name: Cache node modules
        id: cache-npm
        uses: actions/cache@v4
        env:
          cache-name: cache-node-modules
        with:
          path: ~/.npm
          key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ hashFiles('**/package-lock.json') }}
          restore-keys: |
            ${{ runner.os }}-build-${{ env.cache-name }}-
            ${{ runner.os }}-build-
            ${{ runner.os }}-

      - name: Install dependencies
        run: npm ci
      - uses: pnpm/action-setup@v2
        name: Install pnpm
        with:
          version: 9
          run_install: false

      - name: Get pnpm store directory
        shell: bash
        run: |
          echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV

      - name: Cache node modules
        id: cache-pnpm
        uses: actions/cache@v4
        with:
          path: ${{ env.STORE_PATH }}
          key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
          restore-keys: |
            ${{ runner.os }}-pnpm-store-

      - name: Install dependencies
        run: pnpm install

      - name: Build and Publish to Oxygen
        run: npx shopify hydrogen deploy
        env:
          SHOPIFY_HYDROGEN_DEPLOYMENT_TOKEN: ${{ secrets.OXYGEN_DEPLOYMENT_TOKEN_1000016008 }}