Hydrogen Developer

The hydrogen-developer agent carries all conventions for building Shopify Hydrogen storefronts using React, Remix (React Router v7), TypeScript, the Storefront API, and Sanity CMS. Activate it at the start of every Hydrogen project session.

activate_agent("hydrogen-developer")

What It Covers

Monorepo structure: Storefront (app/), Sanity Studio (admin/)
Component taxonomy: UI primitives, commerce components, CMS-driven sections, routes
Build order: Tokens, UI primitives, commerce components, sections, routes
GraphQL organization: Fragments, queries, mutations separated by data source (Shopify / Sanity)
Sanity integration: Schema naming conventions, section pattern across both workspaces, type generation, multi-dataset config
Token system: CSS custom properties or Tailwind config
TypeScript: Strict mode, Props interfaces, JSDoc, no any
Server-first rendering: Default to server components, loaders for data
Validation: tsc --noEmit, ESLint, pnpm build
Performance patterns: Streaming, caching strategies, code splitting, parallel data loading
Figma config: clientLanguages: "typescript,css,react", clientFrameworks: "remix,hydrogen"

Monorepo Structure

.
├── app/                        # Hydrogen storefront
│   ├── components/
│   │   ├── ui/                 # Primitive UI (Button, Icon, Input)
│   │   ├── commerce/           # Commerce composites (ProductCard, CartLineItem)
│   │   └── sections/           # CMS-driven sections (HeroBanner, FeaturedCollection)
│   ├── graphql/
│   │   ├── shopify/            # Storefront API (fragments, queries, mutations)
│   │   └── sanity/             # Sanity GROQ (fragments, queries)
│   ├── helpers/
│   ├── hooks/
│   ├── routes/
│   ├── styles/
│   └── root.tsx
├── admin/                      # Sanity CMS Studio
│   ├── src/schemas/
│   │   ├── documents/          # Singleton and collection content
│   │   ├── objects/            # Reusable field groups
│   │   ├── pages/              # Page-level content types
│   │   ├── sections/           # CMS section schemas
│   │   ├── settings/           # Global settings
│   │   └── templates/          # Page templates
│   ├── sanity.config.ts
│   └── package.json
├── pnpm-workspace.yaml
├── .mcp.json
├── CONVENTIONS.md
└── INSTRUCTIONS.md

The Section Pattern

Every CMS-driven section spans both workspaces:

Schema in admin/src/schemas/sections/section{Name}.js
Component in app/src/components/Sections/{Name}/
Fragment in app/src/graphql/sanity/fragments/sections/
Type in app/src/types/Sections/

When building a new section, create all four files.

Component Types

Type	Purpose	Location	Has Loader
UI Primitive	Reusable atomic element	`app/components/ui/{Name}.tsx`	No
Commerce Component	Business-logic composite	`app/components/commerce/{Name}.tsx`	No
Section	CMS-driven page section	`app/components/Sections/{Name}/`	No
Route	URL-mapped page with data loading	`app/routes/{path}.tsx`	Yes

Commands

Task	Command
Set up or onboard a project	`setup`
Extract tokens, icons, logos from Figma	`design-system`
Build components, sections, routes	`build`
Visual QA against design reference	`refine`
Accessibility audit	`accessibility`
Performance optimisation	`performance`
SEO audit	`seo`
Code audit	`audit`
Dependency updates and version upgrades	`maintenance`
Commit changes	`commit`

Session Init

Before writing any code, the agent instructs:

Load get_conventions for universal rules and MCP toolchain
Read the project’s CONVENTIONS.md for tokens, component APIs, GraphQL fragments, overrides
Call get_project_context for project memory