How @shopify/hydrogen handles runtime failures: when to throw, when to log, when to expose reactive state, and how logs are formatted, configured, and tested. Apply this policy to any new or changed runtime logic in packages/hydrogen/src.
Taxonomy
Pick the mechanism from the failure class. Never double-report (throw AND log the same failure).
| Failure class | Mechanism | Examples |
|---|---|---|
| Programming errors | Throw a typed error synchronously. | Bad arguments, invariant violations. |
| Request-scoped failures with a caller | Throw a typed error; the caller decides retry/render. | StorefrontApiError, CustomerAccountApiError, CartActionError, CartNetworkError. |
| Server handlers with internal recovery | Catch failures, log via the scoped logger, return a structured error Response. |
Cart server handler catches a network failure and returns 500 with a JSON error body. |
| Background browser failures | Scoped logger at error level. |
Runtime script loads, background cart loads, analytics publish failures. |
| Misuse / degradation | Scoped logger at warn level. |
Mock shop detected, analytics destination misconfigured, deprecated option passed. |
| Buyer-visible user errors | Reactive state only — never logged. | Cart userErrors surfaced to the UI; the user corrects and retries. |
Logger contract
Internal call convention
getLogger is internal — not part of the public package API.
import { getLogger } from "../logging"; // relative import within src/
const log = getLogger("cart");
log.error("cart initial load failed", { error });
getLogger(scope)returns a lazily-resolved scoped logger. Prefer one module-levelconst logper file when the scope is static. Use stable subsystem scopes; proxy descriptors provide dynamic scopes.- Messages are unprefixed, lowercase-leaning, and without trailing colons; the sink owns formatting.
context.errorbecomes a separate console argument; other context keys become a trailing object.- Never call
console.*directly in runtime files underpackages/hydrogen/src— theno-consolelint rule enforces this. Sanctioned runtime exceptions: the built-in sink insrc/core/logging/logging.ts, the serialized consent bootstrap insrc/core/shopify-scripts/consent-script.ts, and the CLI. Tests may spy on or mockconsolefor the exceptions listed below.
HydrogenLogger
A minimal structural interface with six level methods:
interface HydrogenLogger {
trace: (message: string, context?: LogContext) => void;
debug: (message: string, context?: LogContext) => void;
info: (message: string, context?: LogContext) => void;
warn: (message: string, context?: LogContext) => void;
error: (message: string, context?: LogContext) => void;
fatal: (message: string, context?: LogContext) => void;
}
LogContext is { scope?: string; error?: unknown; [key: string]: unknown }.
configureLogging
import { configureLogging } from "@shopify/hydrogen";
const logger = {
trace: console.debug,
debug: console.debug,
info: console.info,
warn: console.warn,
error: console.error,
fatal: console.error,
};
configureLogging({ logger, level: "warn" });
- Global, called once at startup (app entry on the browser, module init on the server).
logger— anyHydrogenLogger; defaults to the built-in console sink.level— minimum severity forwarded; defaults to"info".- Last-call-wins: reconfiguring applies the new options.
Default console sink
Formats entries as [hydrogen:<level>:<scope>] <message>, followed by context.error (if present) and a trailing object of remaining context fields.
Serialized inline scripts — documented exception
Inline/CDN scripts that Hydrogen serializes into HTML are compiled to strings via import … with { type: "script" } chains. They never see the app bundle's global state, so configureLogging cannot reach them. The analytics bootstrap path and its bus/destination-manager modules write to console with the standard [hydrogen:<level>:<scope>] prefix via the consoleLogger sink — when writing code in a serialized-script import chain that shares modules with the app bundle, use consoleLogger directly with an explicit { scope } instead of getLogger. Serialized-only leaf modules (the consent bootstrap) hardcode the prefix in a plain console.* call instead, so the logging module is not inlined into every HTML response.
Non-goals
- Per-request child loggers / request correlation. Scopes are per-subsystem, not per-request.
Test expectations
- Failure paths inject a test logger instead of mocking
console:configureLogging({ logger })with sixvi.fn()methods,configureLogging({})inafterEachto restore the defaults. Assert(message, { scope, ...context })— no prefix strings. - Exceptions that still spy
console: serialized inline-script import chains (analytics bus/destination-manager, consent) write toconsoledirectly, andlogging.test.tsverifies the sink's own[hydrogen:<level>:<scope>]formatting. - The
no-consolelint rule enforces the policy: the sanctionedconsolecall sites aresrc/core/logging/logging.tsand the serialized consent bootstrapsrc/core/shopify-scripts/consent-script.ts, each carrying an inlineoxlint-disable-next-line no-console. CLI and test files are exempt.