gitntg/shophydr icon
public
Published on 3/30/2025
Shopify-Hydrogen

hydrogen/shopify focused rules for remix/react store

Rules
shophydr
## Core Principles:
  - Optimize for Hydrogens **streaming and caching** model to enhance performance.
  - Use **Shopifys Storefront API** effectively, following best practices for queries and mutations.
  - Ensure all components are **server-first** but leverage **client-side hydration** where needed.
  - Use **Tailwind CSS** efficiently with Hydrogens best practices for styling.
  - Prioritize **authentication and session handling** for Shopify customers.

## Routing & Layout in Remix
  - Use `loader` functions for **server-side data fetching**.
  - Prefer **nested routes** for modular page structures.
  - Use `useLoaderData()` instead of client-side fetching where possible.
  - Optimize Remixs **deferred loading** to improve perceived performance.

## Shopify Storefront API Usage
  - Always fetch data using **GraphQL queries** in `loader` functions.
  - Minimize API requests by batching queries efficiently.
  - Cache queries where appropriate to **reduce unnecessary API calls**.
  - Avoid over-fetching request **only the necessary fields**.
  - Use Shopifys **recommended pagination techniques** (`cursor`-based pagination).

## Hydrogen & Performance Optimizations
  - Utilize **Hydrogens streaming API** to improve time-to-first-byte (TTFB).
  - Use `CacheNone()` or `CacheLong()` selectively to control caching behavior.
  - Edge caching Ensure frequently accessed data is cached at the CDN level.
  - Prefer `useShopQuery()` over manual API calls for **consistent data fetching**.
  - Offload **expensive computations to server-side** where possible.

## Styling & Tailwind CSS
  - Use **Hydrogens built-in Tailwind setup** for consistency.
  - Avoid excessive utility classes by leveraging **Tailwinds theme and variants**.
  - Structure styles efficiently to **minimize CSS bloat**.
  - Use **Tailwinds responsive utilities** to ensure a mobile-first approach.

## Authentication & Session Handling
  - Implement Shopifys **customer authentication** using `customerAccessToken`.
  - Store authentication tokens securely in **server-side sessions**.
  - Use Remix loaders and actions to **handle login and logout server-side**.
  - Ensure **session expiry is handled gracefully** to prevent errors.
  - Implement **SSR-friendly authentication checks** to avoid hydration mismatches.

## Deployment on Shopify Oxygen
  - Follow **Shopifys guidelines for edge deployment**.
  - Ensure **Remix server handlers** are optimized for Oxygen.
  - Use `@shopify/hydrogen` utilities for **seamless integration with Shopify's infrastructure**.
  - Test deployments using Shopifys **Oxygen preview environment** before production.

## Component & Code Best Practices
  - Prefer **server components** whenever possible to reduce client-side JavaScript.
  - Use **lazy loading** (`React.lazy()`, `Suspense`) for non-critical UI components.
  - Keep components **small, modular, and reusable**.
  - Avoid excessive **client-side state management**; leverage Remix loaders instead.
  - Use **React Error Boundaries** for graceful error handling.

## Key Conventions:
  - Always **fetch data in loaders**; minimize client-side API calls.
  - Structure routes **to take full advantage of Remixs nested routing**.
  - Use **server caching strategies** to reduce redundant Storefront API calls.
  - Optimize **Hydrogens streaming features** for a fast user experience.
  - Follow **Shopifys best practices for deployment on Oxygen**.

Refer to Shopifys Hydrogen and Remix documentation for additional best practices.