Debugging and testing Hydrogen apps

Hydrogen includes several tools to help you debug your project, both when developing locally and in production.

Subrequest profiler

Inspect your app's data queries to find slow or oversized API calls and eliminate request waterfalls

Error console

Isolate production errors and stack-trace offending code directly from the Shopify admin

Bundle size inspector

Analyze your Hydrogen project's production bundle to target dependency bloat and reduce startup time

Server-side debugger

Attach a debugger utility to inspect server-side breakpoints in your IDE and browser

CPU profiler

Track down sluggish processes that could delay your Hydrogen app starts or trigger timeouts

Log drains

With Shopify Plus, archive and analyze Oxygen production telemetry with third-party logging services

These are some issues developers often run into when building with Hydrogen, and how to investigate or fix them:

Sub-optimal API queries can make sites feel slow. Large or complex queries can delay API response times, and too many synchronous requests can lead to a waterfall effect that blocks rendering. To start addressing these issues:

1. Use Hydrogen's Subrequest profiler to isolate and eliminate bloat.
2. Learn about caching Shopify API data with Hydrogen.

By default, Hydrogen caches all queries to the Storefront API. However, it's likely you can cache certain parts of your app for longer than the default time period. To fine-tune your caching:

1. Learn about caching Shopify API data with Hydrogen.
2. Consider when you could use full-page caching.
3. Use the Subrequest profiler to check cache hits and misses.

Certain dependencies can increase your compiled app bundle size, contributing to slower start times and sluggish performance. Analyze your dependency graph to find the offending packages:

1. Use the bundle size analyzer to find large dependencies.
2. Attach a debugger to identify bottlenecks in server-side code.

Deploying to Oxygen could fail for several reasons. Some common ways to diagnose these errors:

1. In the Shopify admin, check the deployment logs on the deployment detail page.
2. Check that you're not using Node.js APIs that aren't available in Oxygen's Worker-based runtime.
3. Check that you're not exceeding Oxygen's file size limits. Try compressing files, or using a third-party CDN for required assets that exceed Oxygen limits.
4. Profile your CPU startup time to find processes that might be timing out.
5. Inspect your bundle size to remove unecessary or bloated dependencies.

React hydration errors in the browser console indicate that the HTML rendered on the server doesn't match the HTML that React found on the browser when adding interactivity with JavaScript. This can happen for multiple reasons and is likely specific to your code, so there's no single solution that can fix the problem. Generally, you can try to comment out or remove part of your code to isolate the issue and find the root cause.

A common cause of hydration mismatch in React and Remix apps is that a browser extension modifies the HTML of the page before React uses it. You can check if this is the case in your app by opening incognito mode or private browsing without browser extensions. Refer to this issue for more information.

You can add end-to-end testing of your Hydrogen deployments with authentication bypass tokens. These tokens allow third-party CI/CD platforms to securely access your deployments for testing purposes.