← mostly_words

The Solo Dev's Guide to Hydrogen Observability

· 5 min read
Interior of Saint John’s Church in Toledo (1861)

I won’t be sharing my business here. I don’t want this to seem like a plug for it, just hoping to share a useful strategy I’ve employed that may help others. Anyways…

I see the sentiment online that building and running a Shopify Hydrogen site is impossible if you're doing it yourself. That it's “only worth it if you’re doing more than “100 million A.R.R.” Ok, that may be a bit of a stretch, but I can see how people would feel this way. However, with new AI tooling, this possibility is becoming much more feasible.

I run a Shopify Hydrogen storefront by myself. Well, kind of. I haven't launched my store front yet, but I have everything in place now to do so, and it’s allowed me to get back to focusing on the products I want to be designing and testing rather than all of this infrastructure stuff. My goal after I launch is to focus on the parts where I get to be creative and build, rather than sitting back and monitoring logs and metrics.

Another disclaimer, I have a bachelors in Computer Science and have been working as a software engineer professionally for about 3 years. I was already very familiar with coding and environments that are similar to Hydrogen. This obviously gives me a huge leg up in this process compared to someone like a shoe cobbler trying to dive into all of this. However, that is just concerning the building part of your Hydrogen site, and you could pay someone to do that if you really wanted. Hopefully that's become faster and cheaper now as well with AI. My thoughts here refer to everything after that, which I think even the shoe cobbler could figure out.

The Setup

My stack really isn't anything crazy. I kept it simple:

If you are reading this, you probably already know about Hydrogen, but it’s basically just a headless e-commerce platform powered by Shopify's ecosystem.

Sentry is what I’m using for the application monitoring. It reports different errors that may get thrown whenever your site is deployed. I’m using the free tier, which should be more than enough for now, but bumping up to the team tier currently only costs like 25 bucks and could be worth it depending on your use case.

Next is Subtext (I help build this so reach out with any questions). This gives me access to session replays for my site, but not in the traditional sense you may associate that phrase with. Let me back up for a second. When something goes wrong on my site, I want to be able to see that user's session where the error happened to get the full context of what was faced. However, watching session replays is super tedious and would take away from doing what I actually want to be working on. Subtext handles this by allowing my own AI agents to watch the sessions instead of me, and it does a pretty good job. I’m using the free tier here as well.

With this setup, every single Sentry event includes the exact URL of the session replay where the error occurred. You can find the integration guide here: link. In other words, every crime comes with security cam footage. I can pass that session into subtext to get a deep analysis on things sentry may have missed. This is all I really need to cover blind spots in my setup.

Automation

To do the watching, I built a small Python service called hydrogen-observability. It basically loops, handling all the grunt work for me:

  1. Poll Sentry every 60 seconds for new issues. I used polling for this, but you could use webhooks as well. Just a little extra set up work. Both options are supported on the Sentry free tier.
  2. Extract the Subtext session URL from the event on every new issue.
  3. Hand it off to an AI agent. The service shells out to a headless instance of Claude Code with a Subtext plugin. This gives the agent actual access to the session—the events, the console, the network, everything. My prompt just asks it for a structured report: a summary, a timeline, user impact, likely cause, and suggested next steps.
  4. Publish the report to a local dashboard. Whenever a new issue pops up, it shows as a card. A few minutes later, the AI analysis lands right under it.
  5. Text me if things are on fire. Fatal-level issues send an SMS the second they are detected, before the AI even finishes its analysis.

So, instead of waking up to a Sentry email yelling TypeError: Cannot read properties of undefined (reading 'merchandise'), I open my dashboard and get something like this:

Summary: User attempted checkout with a discount code applied. The cart optimistic update raced the discount mutation, leaving the cart line without a merchandise reference. User retried three times over 90 seconds, then abandoned a $140 cart.

Suggested next steps: Guard the cart line render against missing merchandise; queue the discount mutation behind the pending add-to-cart.

That is triage I would have eventually done manually. Now it's all automated for me. I’ll make this repo public soon if anyone is interested in forking or collaborating on it. Check out my github for updates.

Boring details

This is where things get a bit scrappy, but it works fine at my scale.

  • It runs on my Unraid box. The whole operation is just one Docker container. For development, I run it on my Mac via Docker Desktop. In production, it sits on my Unraid server right next to my Plex instance. It even uses an Unraid template so it shows up in my web UI like any other app. I use SQLite for storage, one volume for data, and one for the agent's credentials.
  • Alerts are email-to-SMS. No Twilio account or expensive alerting SaaS. The service simply sends a short, plain email via SMTP to my cell carrier's email-to-SMS gateway (e.g., myphone@vtext.com). Yes, carriers are slowly killing these gateways, but I'll ride this out until I can’t anymore.
  • Severity gates the noise. I only get a text for fatal and error level issues. Everything else queues up quietly for analysis, and I just skim the dashboard when I have time. It deduplicates alerts too, meaning a sudden spike of 400 identical errors gives me one single grouping, not 400 separate.
  • Issues without a session still get flagged. If an error doesn't have a Subtext link attached (mostly server-side stuff), it shows up on the dashboard as "skipped." I know it exists, I just don't get the automated replay analysis for it.

Steal This

This pattern easily generalizes beyond Hydrogen, and even beyond just Subtext and Sentry. The core loop is simple:

Error tracker → Link to session evidence → Agent analyzes the evidence → Human-readable report + alert

The pieces that made this incredibly cheap to build were simple choices: polling instead of webhooks (meaning zero infrastructure), a headless coding agent with a plugin instead of a bespoke ML pipeline (the session-analysis capability already existed, I just automated invoking it), SQLite instead of a heavy database server, and email-to-SMS instead of paying for an alerting product.

Overall, the footprint is small, and it reuses components that I already had set up. Even buying a mac mini would be perfectly adequate for handling everything here. Hell, buy two more and now you can run your own model. I’ll eventually have to fight SMS demons later once the carrier shuts my access off, but I’ll just find the next best thing.

Anyways, if you made it down here, thank you for reading. Always remember, “if you demand human attention, demonstrate human effort.”