Getting Started with Shopify Hydrogen: Headless Commerce Guide

What is Shopify Hydrogen?

Shopify Hydrogen is a React-based framework for headless commerce built by Shopify. Unlike traditional Shopify themes, it offers complete customization freedom and exceptional performance.

Why Choose Hydrogen?

Hydrogen enables capabilities that traditional Shopify themes cannot deliver:

• Blazing Fast Performance: Server-Side Rendering (SSR) for instant page loads
• Complete Design Freedom: Build custom UIs with React components
• Modern Web Stack: Leverage Remix, Vite, Tailwind CSS, and more
• Excellent Developer Experience: TypeScript, Hot Module Replacement, strong typing

Setup Guide

1. Create Your Project

npm create @shopify/hydrogen@latest

Follow the interactive prompts to choose your project name, language (TypeScript recommended), and styling approach.

2. Start Development Server

cd your-hydrogen-store
npm install
npm run dev

Your local development server will start at http://localhost:3000.

3. Connect to Shopify Store

Add your Storefront API credentials from Shopify Admin to .env:

PUBLIC_STOREFRONT_API_TOKEN=your_token_here
PUBLIC_STORE_DOMAIN=your-store.myshopify.com

Basic Component Structure

Product Listing Page Example

// app/routes/products._index.tsx
import { json, type LoaderFunctionArgs } from '@shopify/remix-oxygen';
import { useLoaderData } from '@remix-run/react';
import { getPaginationVariables } from '@shopify/hydrogen';

export async function loader({ context, request }: LoaderFunctionArgs) {
  const paginationVariables = getPaginationVariables(request, {
    pageBy: 12,
  });

  const { products } = await context.storefront.query(PRODUCTS_QUERY, {
    variables: {
      ...paginationVariables,
    },
  });

  return json({ products });
}

export default function Products() {
  const { products } = useLoaderData<typeof loader>();

  return (
    <div className="products-grid">
      {products.nodes.map((product) => (
        <ProductCard key={product.id} product={product} />
      ))}
    </div>
  );
}

const PRODUCTS_QUERY = `#graphql
  query Products($first: Int) {
    products(first: $first) {
      nodes {
        id
        title
        handle
        priceRange {
          minVariantPrice {
            amount
            currencyCode
          }
        }
        featuredImage {
          url
          altText
        }
      }
    }
  }
`;

Japanese Market Optimization

1. Japanese Font Optimization

// app/root.tsx
import { links } from './styles/fonts';

export const links: LinksFunction = () => [
  ...fonts,
  { rel: 'stylesheet', href: styles },
];

2. Japanese Payment Methods

Hydrogen Checkout seamlessly integrates Japanese payment options:

• Shopify Payments: JCB, American Express support
• Convenience Store Payment: Komoju, PAY.JP integration
• Cash on Delivery: Implement via custom Checkout extensions

3. Delivery Options Customization

// Delivery date/time picker implementation
export function DeliveryDatePicker() {
  const [selectedDate, setSelectedDate] = useState<Date | null>(null);
  const [selectedTime, setSelectedTime] = useState<string>('');

  const timeSlots = [
    'Morning (8:00-12:00)',
    '14:00-16:00',
    '16:00-18:00',
    '18:00-20:00',
    '19:00-21:00',
  ];

  return (
    <div className="delivery-picker">
      <DatePicker
        selected={selectedDate}
        onChange={setSelectedDate}
        minDate={new Date()}
        locale="en"
      />
      <select value={selectedTime} onChange={(e) => setSelectedTime(e.target.value)}>
        {timeSlots.map((slot) => (
          <option key={slot} value={slot}>{slot}</option>
        ))}
      </select>
    </div>
  );
}

Performance Optimization

1. Image Optimization

Hydrogen’s <Image> component automatically handles:

• WebP/AVIF conversion
• Responsive image generation
• Lazy loading
• Shopify CDN utilization

import { Image } from '@shopify/hydrogen';

<Image
  data={product.featuredImage}
  sizes="(min-width: 45em) 50vw, 100vw"
  aspectRatio="1/1"
/>

2. Caching Strategy

export async function loader({ context }: LoaderFunctionArgs) {
  const { products } = await context.storefront.query(PRODUCTS_QUERY, {
    cache: context.storefront.CacheLong(), // 1 hour cache
  });

  return json({ products });
}

Deployment

Deploy to Oxygen (Shopify’s Recommended Platform)

npm run build
npx shopify hydrogen deploy

Oxygen provides global edge network delivery, ensuring optimal performance for users worldwide, including Japan.

Vercel/Netlify Deployment Also Supported

Since Hydrogen is a standard Remix app, it works on other platforms too.

Summary

Shopify Hydrogen is ideal when you need:

✅ Advanced Customization: Build unique brand experiences ✅ Performance Focus: Optimize Core Web Vitals ✅ Modern Development: Leverage React and TypeScript

For standard e-commerce sites, Shopify Themes (like Dawn) may be sufficient.

Choose the right approach based on your project requirements.

---

DEMETIO specializes in building high-performance e-commerce sites with Shopify Hydrogen.

Considering headless commerce? Get in touch.