Troubleshooting tips when deploying Hydrogen storefronts to Oxygen

[kcarra]

Recently our team has deployed our Hydrogen storefront to Oxygen, and for the most part it has "just worked" when following the deployment documentation. However, there have been some pain points and debugging that the team has needed to do. Hopefully this discussion will help outline some of the issues we've faced and prevent others from running into the same issues.

• Some things aren't supported in serverless Cloudflare workers
  We started building our storefront before Oxygen was available as a deployment option. We were using things such as Buffer to generate base-64 encoded cache key strings. This is one of those objects that is not supported in Cloudflare workers. Once we deployed to Oxygen, the server runtime logs did make it pretty obvious that Buffer was not available. However, it's not always obvious what third party libraries are using. We ran into an issue with graphql-request using XMLHttpRequest by default. This will work when running your storefront locally but will break when deployed to Oxygen. This leads to my next point which is debugging in miniflare. Relevant issues and discussions related to this: Fix TS transpile in CLI hydrogen#1273, Handle all cart mutations on /cart actions hydrogen#93

• Running the storefront locally in miniflare using shopify hydrogen preview
  This is a great way to emulate running your hydrogen app in a cloudflare worker. From what I've seen, the logging in miniflare is much more verbose than the runtime logs in the hydrogen storefront in Shopify. This is what allowed us to debug the issue with graphql-request using XMLHttpRequest by default. Using miniflare with shopify hydrogen preview did come with a set of challenges which I'm confident will be resolved shortly. One being the shopify hydrogen preview does not populate the miniflare global bindings with values in your .env file. See this issue: fix customer client hydrogen#1901. As a result anything that uses Oxygen.env will not be available in miniflare.

• Github actions with shopify/oxygenctl-action && shopify/github-deployment-action
  By default when you connect your storefront to github and vice versa in Shopify it will create a Github actions workflow for you in a separate pr using the shopify/oxygenctl-action and shopify/github-deployment-action actions. These are great for simple GH workflows, but have some challenges with more complex workflows. Both actions assume that they are being used in a job that gets triggered in a on.push event. In our case we wanted to trigger a preview deploy when a pull request was opened against a staging branch. As a result some inputs to these actions will fail since they assume github.event.head_commit is present, which isn't the case for on.pull_request events. See this issue for ways to get around this github.event.head_commit not available on pull_request events oxygenctl-action#35

Hopefully this is helpful to others, happy to elaborate more on any of these points.