hydrogen

# Agent Guidelines

## API Design Principles

When designing or adjusting APIs for the `hydrogen` package, closely follow the following principles:

- **No magic**: Prefer explicit over implicit.
- **Composable blocks**: Keep domains and features separated by composable parts.
- **Poka Yoke / Affordance**: Make it impossible to "hold it wrong".

## Testing

- Tests and type tests may use type assertions, `import()` type annotations, explicit `any`, and higher-complexity setup when that keeps mocks or compile-time assertions clear.
- Non-null assertions (`!`) are still forbidden in tests. Use an assertion helper instead so failures include a useful message.
- In Hydrogen package tests, import `assert` from `packages/hydrogen/src/core/test-utils.ts` rather than using `!`.

## MiniOxygen

- `packages/mini-oxygen` keeps its existing code style: `oxfmt` skips it, and `.oxlintrc.json` turns off the rules its code breaks, including the testing rules above. Don't reformat or restyle it as part of unrelated changes.

## Local HTTPS for Examples

- Account-enabled framework examples use `https://local.tryhydrogen.dev:5173` for Customer Account OAuth callback testing.
- Vite-based examples consume Hydrogen's default certificates. Certificates are provisioned automatically on `dev:https` startup. This downloads a pinned, checksum-verified mkcert release, trusts the local certificate authority, and creates the certificates under `~/.shopify/hydrogen/certs/`. Nuxt and SolidStart may need one restart after first-run provisioning so their outer dev servers can load the certificate files.
- Outside CI, the local HTTPS plugin uses Shopify CLI to link an unlinked Hydrogen storefront and push the Customer Account callback, JavaScript origin, and logout URLs. Failures fall back to printing the values for manual configuration.
- The Next.js example provisions its own certificate. The Hydrogen example uses the Shopify CLI tunnel flow.
- Run the relevant example with `pnpm --filter @shopify/hydrogen-example-<name> dev:https` when that example provides the script.
- Reproduce the trusted local HTTPS CI check with `pnpm run test:local-https`. It starts the React Router template, so first build the template's workspace packages (`pnpm turbo run build --filter='@shopify/hydrogen-template-react-router^...'`, or `pnpm run build:pkgs`) and make sure certificates exist under `~/.shopify/hydrogen/certs/` (any prior `dev:https` run, or `node packages/hydrogen/bin/hydrogen.mjs certs install`).

More agent context in Shopify/hydrogen

31 other files this repository gives its agents.