Deploy, Observe, Debug: Making the path to production painless

Black Friday Cyber Monday 2023 was a watershed moment for Hydrogen. Hundreds of merchants were relying on the Hydrogen and Oxygen stack to serve millions of customers during the busiest shopping week of the year. Oxygen handled millions of requests per minute without breaking a sweat, meaning shoppers consistently enjoyed fast browsing and breezed through to checkout throughout the BFCM weekend.

In short, Hydrogen running on Oxygen is fast, easier than ever to build with, and customers love the results. But the job is never done: we believe in continuous improvement and know that there are still opportunities to make the Hydrogen path to production even more robust. That’s why we’ve dedicated the last few months to making Hydrogen’s developer experience more seamless than ever.

From more flexible deployments to advanced debugging tools, our latest release covers a wide range of DX improvements that fall into three categories:

• Deploy: Push your Hydrogen app to Oxygen from any platform, with more flexibility.
• Observe: Monitor, share, and test your deployments in production more easily.
• Debug: Find, fix, and prevent bugs before they ship with a suite of new developer tools.

Let’s run down this complete list of new features and functionality.

Deploy

From the very start, Hydrogen and Oxygen shipped with continuous deployment built-in. Oxygen watches your GitHub repo for changes, then automatically deploys your app with every push. That worked great for merchants using GitHub, but we heard from others who wanted the freedom to deploy from other CI/CD platforms, or using other version control systems.

Now you can do that — with the new Hydrogen CLI deploy command. Just run npx shopify hydrogen deploy from your terminal to deploy your Hydrogen app to Oxygen in moments.

You can create multiple deployment tokens to deploy from any third-party context. For instance, you could now deploy to Oxygen from a wider selection of version-control platforms, such as BitBucket or GitLab. Or build your own CI/CD pipeline, based on your unique requirements.

Hydrogen’s fully automated GitHub support isn’t going anywhere. You can still connect your storefront to a GitHub repo in a few clicks, and everything just works. But for more complex headless architectures, deploy enables limitless flexibility. We’re excited to see what you build with these new capabilities.

Observe

We’ve now made it easier than ever to observe, monitor, and test your Hydrogen apps when deploying to Oxygen. These new features allow developers to track down bugs faster, let stakeholders easily review and approve updates before they ship, and unlock automated end-to-end testing for every deployment.

Enhanced error console

Deployment logs now provide complete source maps. This means you can accurately trace any error in your compiled app back to its source — down to the individual file, line, and column number. This makes it far easier to track down the root cause of any problem with your app, and much faster to fix. Click on any error in the deployment log console to open an annotated version of your source code, with the offending line highlighted.

We’ve also added more filtering options for your deployment logs, so tracking individual error types is faster. You can narrow your deployment log view to warnings or errors with one click each, and save those filtered views for faster access later.

Deployment access tokens

We’ve recently introduced a more flexible token-based system for creating and managing shareable links for your preview deployments. Just like before, you can quickly make any deployment accessible to anyone who knows its URL, making it simple for stakeholders to review update, whether they’re logged-in or not. But now you can also rotate or revoke your share tokens for finer-grained access control and enhanced security.

End-to-end testing

Token-based deployment access unlocks another, even more powerful feature: full support for end-to-end testing (E2E) and continuous integration.

Now when you create a deployment from any context with npx shopify hydrogen deploy, pass the --auth-bypass-token flag to generate a temporary deployment access token. You can then use that token to give any automated testing platforms full access to your private deployment. And this specialized token type automatically expires after two hours, so you don’t have to worry about your deployments being exposed to the web indefinitely.

Debug

Of course, the best time to find and fix a bug is before it ships to production. We’ve been working hard on a suite of developer tools for Hydrogen that help you get more insights into how your app works than ever before, at the earliest stages of development.

Subrequest profiler

Inspect the performance of every data query your Hydrogen app makes with our new subrequest profiler tool. This browser-based console runs alongside your local development environment and gives you complete visibility into every API call.

To get started, open the /subrequest-profiler route in your browser when running your Hydrogen app in a local development environment. You’ll see a flame graph that shows the routes that are being loaded, all the API calls they contain, as well as cache hits and misses. The subrequest profiler makes it possible to search and destroy bloated API queries, eliminate request waterfalls, and fine-tune your caching behavior like never before.

Runtime mirroring

Hydrogen’s local development server is now even closer to parity with Oxygen’s production runtime, so you can be more confident that your app will deploy consistently and reliably. We’ve aligned the development and production runtime in a couple different ways.

First, Hydrogen now wraps Cloudflare’s workerd, the open-source, worker-based JavaScript runtime on which Oxygen is built. This removes the risk of Node.js APIs that work locally, but fail in production. And the development server now returns HTTP headers at parity with production Oxygen.

Second, Hydrogen’s development server now serves your site’s static assets, such as images, through a different local domain, which more closely resembles the way assets are served through Shopify’s CDN. This can help you catch cross-domain asset permission issues before deploying to production, not after.

Server-side debugging

Understanding exactly what’s going on under the hood of your Hydrogen app is now easier, with the release of server-side debugging. If you run the dev command with the --debug flag, you can now attach a debugger to the development server to better understand how your code is working (or not working). Running in debug mode allows you to insert breakpoints in server-side code, so you can step through your app line by line, to zap even the sneakiest bugs. 

Bundle insights

An important way to keep Hydrogen apps feeling fast for shoppers is to deploy the smallest, most efficient bundle. Hydrogen’s default build command has always given you some basic stats about the size of your compiled worker file, but Hydrogen now gives you a lot more detail.

When running build, you’ll see a notification come up in your terminal with a new file path containing your bundle report. Open that HTML file in your browser for an interactive guide to your app bundle and dependencies. This makes it more intuitive to spot packages and libraries that could be bloating your app and slowing performance.

We’ve also added the debug cpu command, which will profile your bundle’s CPU startup time. This is important for minimizing cold starts — smaller bundles tend to start faster, reducing latency and speeding up your site for users. This command can only provide approximations based on your local machine’s CPU, but this can still be an important signal to measure when fine-tuning your build.

Upgrade

These are just some of the improvements we’ve made to Hydrogen over the last few months. Among other things, Hydrogen upgraded its foundational framework, Remix, to version 2. We’ve also added support for new Shopify APIs that make handling customer data more secure and compliant across the board. First, the Customer Account API provides a more modern, scalable, and secure way to manage customer identity and authentication. Second, the Customer Privacy API allows you to manage marketing consent and privacy data across Shopify’s platform, including Pixels, Checkout, and other services. We’ve also recently added more example apps to our GitHub repo to better showcase the flexibility and power of Hydrogen for any headless commerce application.

We know it can be a chore to keep your apps up to date with so many new features and capabilities shipping. So we added one more thing to help: npx shopify hydrogen upgrade is a new command available today through the Hydrogen CLI. When you run it, you’ll see options to upgrade to the latest version of Hydrogen (or any interim version). The CLI will handle upgrading your dependencies, and generate a customized changelog with details about how to make updates to your code base, if needed. All this means you can adopt new Hydrogen features faster, with greater confidence.

All in all, it’s been a busy few months. Hundreds of merchants now run the Hydrogen and Oxygen stack in production, generating billions of dollars in sales. We believe that the efforts we’ve put into Hydrogen’s developer experience make it faster and easier than ever for the world’s most ambitious merchants to embrace headless. Try it out today!