Developer Onboarding & Guardrails Cheatsheet for Hydrogen

Introduction

Hydrogen is powerful, but with power comes risk. New developers can accidentally:

• Import a 9MB SDK into Oxygen.
• Expose API keys in loaders.
• Create waterfalling subrequests on PDPs.

Agencies need a guardrails cheatsheet that gives every dev — from junior to senior — a clear set of “if you’re about to…” rules.

Why Guardrails Matter

• ⚡ Faster onboarding.
• 🛡️ Fewer production bugs.
• 📊 Predictable performance + quotas.
• 💸 Less time wasted fixing avoidable mistakes.

👉 Guardrails = agency efficiency + client trust.

Cheatsheet Structure

1. If You’re About to Add a Library…

• ✅ Check bundle size (<5MB total).
• ✅ Prefer modular imports (firebase/firestore/lite vs firebase).
• ❌ Never import Node-only libs (e.g., fs, crypto).

2. If You Fetch Third-Party Data…

• ✅ Use Hydrogen loaders (server-safe).
• ✅ Batch queries + cache hot data.
• ❌ Don’t fetch inside React components.

3. If You Edit PDP/PLP Templates…

• ✅ Profile subrequests with Hydrogen Profiler.
• ✅ Keep <5 subrequests per page.
• ❌ Don’t chain GraphQL queries.

4. If You Expose Config or Keys…

• ✅ Use environment variables.
• ✅ Sign JWTs in Oxygen.
• ❌ Never hardcode secrets in loaders.

Case Example: Onboarding Time Cut

• Before cheatsheet: junior devs took ~3 weeks to ramp up, often broke quotas.
• After cheatsheet: onboarding down to ~5 days.
• Outcome: faster client delivery, fewer deploy failures.

Implementation

• Create /docs/guardrails.md in repo.
• Pair with .copilot-instructions.md for AI training.
• Run CI checks for bundle size + secret exposure.

Conclusion

Hydrogen’s flexibility demands discipline. A developer guardrails cheatsheet gives teams the structure they need to onboard fast, avoid pitfalls, and keep stores stable.

Guardrails don’t slow devs down. They let them drive faster.