hydrogen-forge 0.1.0

package/templates/starter/.graphqlrc.ts

@@ -0,0 +1,27 @@
+import type {IGraphQLConfig} from 'graphql-config';
+import {getSchema} from '@shopify/hydrogen-codegen';
+
+/**
+ * GraphQL Config
+ * @see https://the-guild.dev/graphql/config/docs/user/usage
+ * @type {IGraphQLConfig}
+ */
+export default {
+  projects: {
+    default: {
+      schema: getSchema('storefront'),
+      documents: [
+        './*.{ts,tsx,js,jsx}',
+        './app/**/*.{ts,tsx,js,jsx}',
+        '!./app/graphql/**/*.{ts,tsx,js,jsx}',
+      ],
+    },
+
+    customer: {
+      schema: getSchema('customer-account'),
+      documents: ['./app/graphql/customer-account/*.{ts,tsx,js,jsx}'],
+    },
+
+    // Add your own GraphQL projects here for CMS, Shopify Admin API, etc.
+  },
+} as IGraphQLConfig;

package/templates/starter/README.md

@@ -0,0 +1,117 @@
+# Hydrogen Forge Starter
+
+A developer-focused Shopify Hydrogen starter template with TypeScript strict mode and Tailwind CSS.
+
+## Features
+
+- **TypeScript Strict Mode** - Maximum type safety with all strict checks enabled
+- **Tailwind CSS** - Utility-first CSS with custom component classes
+- **React Router 7** - Latest routing with loaders and actions
+- **Shopify Hydrogen** - Official Shopify headless commerce framework
+- **Performance Optimized** - Built for 95+ PageSpeed scores
+
+## Quick Start
+
+### Prerequisites
+
+- Node.js 20+
+- pnpm (recommended) or npm
+- Shopify Partner account with a development store
+
+### Setup
+
+1. **Clone and install:**
+
+```bash
+git clone https://github.com/nathanmcmullendev/hydrogen-forge.git
+cd hydrogen-forge/templates/starter
+pnpm install
+```
+
+2. **Configure environment:**
+
+```bash
+cp .env.example .env
+# Edit .env with your Shopify store credentials
+```
+
+3. **Start development:**
+
+```bash
+pnpm dev
+```
+
+4. **Open browser:**
+
+Navigate to `http://localhost:3000`
+
+## Project Structure
+
+```
+app/
+├── components/       # Reusable UI components
+├── graphql/          # GraphQL fragments and queries
+├── lib/              # Utilities and helpers
+├── routes/           # Page routes (React Router 7)
+├── styles/           # CSS files
+│   ├── reset.css     # CSS reset
+│   └── tailwind.css  # Tailwind directives + custom styles
+└── root.tsx          # App root with layout
+```
+
+## Scripts
+
+| Command          | Description                  |
+| ---------------- | ---------------------------- |
+| `pnpm dev`       | Start development server     |
+| `pnpm build`     | Build for production         |
+| `pnpm preview`   | Preview production build     |
+| `pnpm typecheck` | Run TypeScript type checking |
+| `pnpm lint`      | Run ESLint                   |
+| `pnpm format`    | Format code with Prettier    |
+
+## TypeScript Configuration
+
+This starter uses TypeScript strict mode with additional checks:
+
+- `strict: true` - Enable all strict type-checking options
+- `noUncheckedIndexedAccess: true` - Add undefined to index signatures
+- `exactOptionalPropertyTypes: true` - Exact optional property types
+- `noImplicitReturns: true` - Ensure all code paths return
+
+## Tailwind CSS
+
+Custom component classes are defined in `app/styles/tailwind.css`:
+
+- `.btn`, `.btn-primary`, `.btn-secondary` - Button variants
+- `.input` - Form input styling
+- `.card` - Card component
+- `.badge`, `.badge-sale` - Badge variants
+- `.product-grid` - Product grid layout
+- `.container-narrow` - Centered container
+
+## Deployment
+
+Deploy to Shopify Oxygen:
+
+```bash
+pnpm build
+shopify hydrogen deploy
+```
+
+Or deploy to Vercel, Netlify, or any Node.js hosting.
+
+## Documentation
+
+- [Hydrogen Docs](https://hydrogen.shopify.dev)
+- [React Router 7 Docs](https://reactrouter.com)
+- [Tailwind CSS Docs](https://tailwindcss.com)
+- [Shopify Storefront API](https://shopify.dev/docs/api/storefront)
+
+## License
+
+MIT
+
+---
+
+Part of the [Hydrogen Forge](https://github.com/nathanmcmullendev/hydrogen-forge) ecosystem.

package/templates/starter/app/assets/favicon.svg

@@ -0,0 +1,28 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" fill="none">
+  <style>
+    .stroke {
+      stroke: #000;
+    }
+    .fill {
+      fill: #000;
+    }
+    @media (prefers-color-scheme: dark) {
+      .stroke {
+        stroke: #fff;
+      }
+      .fill {
+        fill: #fff;
+      }
+    }
+  </style>
+  <path
+    class="stroke"
+    fill-rule="evenodd"
+    d="M16.1 16.04 1 8.02 6.16 5.3l5.82 3.09 4.88-2.57-5.82-3.1L16.21 0l15.1 8.02-5.17 2.72-5.5-2.91-4.88 2.57 5.5 2.92-5.16 2.72Z"
+  />
+  <path
+    class="fill"
+    fill-rule="evenodd"
+    d="M16.1 32 1 23.98l5.16-2.72 5.82 3.08 4.88-2.57-5.82-3.08 5.17-2.73 15.1 8.02-5.17 2.72-5.5-2.92-4.88 2.58 5.5 2.92L16.1 32Z"
+  />
+</svg>

package/templates/starter/app/components/AddToCartButton.tsx

@@ -0,0 +1,102 @@
+import {type FetcherWithComponents} from 'react-router';
+import {CartForm, type OptimisticCartLineInput} from '@shopify/hydrogen';
+
+export interface AddToCartButtonProps {
+  analytics?: unknown;
+  children: React.ReactNode;
+  disabled?: boolean;
+  lines: Array<OptimisticCartLineInput>;
+  onClick?: () => void;
+  variant?: 'primary' | 'secondary' | 'outline';
+  size?: 'sm' | 'md' | 'lg';
+  fullWidth?: boolean;
+}
+
+export function AddToCartButton({
+  analytics,
+  children,
+  disabled,
+  lines,
+  onClick,
+  variant = 'primary',
+  size = 'lg',
+  fullWidth = true,
+}: AddToCartButtonProps) {
+  const baseClasses =
+    'inline-flex items-center justify-center font-medium transition-all focus:outline-none focus:ring-2 focus:ring-offset-2 disabled:cursor-not-allowed';
+
+  const variantClasses = {
+    primary:
+      'bg-primary-600 text-white hover:bg-primary-700 focus:ring-primary-500 disabled:bg-secondary-300 disabled:text-secondary-500',
+    secondary:
+      'bg-secondary-900 text-white hover:bg-secondary-800 focus:ring-secondary-500 disabled:bg-secondary-300 disabled:text-secondary-500',
+    outline:
+      'border-2 border-secondary-900 bg-transparent text-secondary-900 hover:bg-secondary-900 hover:text-white focus:ring-secondary-500 disabled:border-secondary-300 disabled:text-secondary-400 disabled:hover:bg-transparent',
+  };
+
+  const sizeClasses = {
+    sm: 'rounded px-3 py-1.5 text-sm',
+    md: 'rounded-md px-4 py-2 text-base',
+    lg: 'rounded-md px-6 py-3 text-base',
+  };
+
+  const widthClass = fullWidth ? 'w-full' : '';
+
+  return (
+    <CartForm route="/cart" inputs={{lines}} action={CartForm.ACTIONS.LinesAdd}>
+      {(fetcher: FetcherWithComponents<unknown>) => {
+        const isLoading = fetcher.state !== 'idle';
+
+        return (
+          <>
+            <input
+              name="analytics"
+              type="hidden"
+              value={JSON.stringify(analytics)}
+            />
+            <button
+              type="submit"
+              onClick={onClick}
+              disabled={disabled || isLoading}
+              className={`${baseClasses} ${variantClasses[variant]} ${sizeClasses[size]} ${widthClass}`}
+            >
+              {isLoading ? (
+                <span className="flex items-center gap-2">
+                  <LoadingSpinner />
+                  Adding...
+                </span>
+              ) : (
+                children
+              )}
+            </button>
+          </>
+        );
+      }}
+    </CartForm>
+  );
+}
+
+function LoadingSpinner() {
+  return (
+    <svg
+      className="h-4 w-4 animate-spin"
+      fill="none"
+      viewBox="0 0 24 24"
+      aria-hidden="true"
+    >
+      <circle
+        className="opacity-25"
+        cx="12"
+        cy="12"
+        r="10"
+        stroke="currentColor"
+        strokeWidth="4"
+      />
+      <path
+        className="opacity-75"
+        fill="currentColor"
+        d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"
+      />
+    </svg>
+  );
+}

package/templates/starter/app/components/Aside.tsx

@@ -0,0 +1,136 @@
+import {
+  createContext,
+  type ReactNode,
+  useContext,
+  useEffect,
+  useState,
+} from 'react';
+
+type AsideType = 'search' | 'cart' | 'mobile' | 'closed';
+type AsideContextValue = {
+  type: AsideType;
+  open: (mode: AsideType) => void;
+  close: () => void;
+};
+
+/**
+ * A side bar component with Overlay
+ * @example
+ * ```jsx
+ * <Aside type="search" heading="SEARCH">
+ *  <input type="search" />
+ *  ...
+ * </Aside>
+ * ```
+ */
+export function Aside({
+  children,
+  heading,
+  type,
+}: {
+  children?: React.ReactNode;
+  type: AsideType;
+  heading: React.ReactNode;
+}) {
+  const {type: activeType, close} = useAside();
+  const expanded = type === activeType;
+
+  useEffect(() => {
+    const abortController = new AbortController();
+
+    if (expanded) {
+      document.addEventListener(
+        'keydown',
+        function handler(event: KeyboardEvent) {
+          if (event.key === 'Escape') {
+            close();
+          }
+        },
+        {signal: abortController.signal},
+      );
+    }
+    return () => abortController.abort();
+  }, [close, expanded]);
+
+  return (
+    <div
+      aria-modal
+      className={`fixed inset-0 z-50 ${expanded ? 'pointer-events-auto' : 'pointer-events-none'}`}
+      role="dialog"
+    >
+      {/* Overlay backdrop */}
+      <button
+        type="button"
+        className={`absolute inset-0 bg-black/50 transition-opacity duration-300 ${
+          expanded ? 'opacity-100' : 'opacity-0'
+        }`}
+        onClick={close}
+        onKeyDown={(e) => e.key === 'Enter' && close()}
+        aria-label="Close menu"
+        tabIndex={expanded ? 0 : -1}
+      />
+
+      {/* Slide-in panel */}
+      <aside
+        className={`absolute right-0 top-0 flex h-full w-full max-w-md flex-col bg-white shadow-xl transition-transform duration-300 ease-out ${
+          expanded ? 'translate-x-0' : 'translate-x-full'
+        }`}
+      >
+        {/* Header */}
+        <header className="flex items-center justify-between border-b border-secondary-200 px-6 py-4">
+          <h3 className="text-lg font-semibold text-secondary-900">
+            {heading}
+          </h3>
+          <button
+            className="inline-flex h-10 w-10 items-center justify-center rounded-md text-secondary-500 transition-colors hover:bg-secondary-100 hover:text-secondary-700"
+            onClick={close}
+            aria-label="Close"
+          >
+            <svg
+              className="h-6 w-6"
+              fill="none"
+              stroke="currentColor"
+              viewBox="0 0 24 24"
+            >
+              <path
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                strokeWidth={2}
+                d="M6 18L18 6M6 6l12 12"
+              />
+            </svg>
+          </button>
+        </header>
+
+        {/* Content */}
+        <main className="flex-1 overflow-y-auto px-6 py-4">{children}</main>
+      </aside>
+    </div>
+  );
+}
+
+const AsideContext = createContext<AsideContextValue | null>(null);
+
+Aside.Provider = function AsideProvider({children}: {children: ReactNode}) {
+  const [type, setType] = useState<AsideType>('closed');
+
+  return (
+    <AsideContext.Provider
+      value={{
+        type,
+        open: setType,
+        close: () => setType('closed'),
+      }}
+    >
+      {children}
+    </AsideContext.Provider>
+  );
+};
+
+export function useAside() {
+  const aside = useContext(AsideContext);
+  if (!aside) {
+    throw new Error('useAside must be used within an AsideProvider');
+  }
+  return aside;
+}

package/templates/starter/app/components/CartLineItem.tsx

@@ -0,0 +1,229 @@
+import type {CartLineUpdateInput} from '@shopify/hydrogen/storefront-api-types';
+import type {CartLayout} from '~/components/CartMain';
+import {CartForm, Image, type OptimisticCartLine} from '@shopify/hydrogen';
+import {useVariantUrl} from '~/lib/variants';
+import {Link} from 'react-router';
+import {ProductPrice} from './ProductPrice';
+import {useAside} from './Aside';
+import type {CartApiQueryFragment} from 'storefrontapi.generated';
+
+type CartLine = OptimisticCartLine<CartApiQueryFragment>;
+
+/**
+ * A single line item in the cart. It displays the product image, title, price.
+ * It also provides controls to update the quantity or remove the line item.
+ */
+export function CartLineItem({
+  layout,
+  line,
+}: {
+  layout: CartLayout;
+  line: CartLine;
+}) {
+  const {id, merchandise} = line;
+  const {product, title, image, selectedOptions} = merchandise;
+  const lineItemUrl = useVariantUrl(product.handle, selectedOptions);
+  const {close} = useAside();
+
+  return (
+    <li
+      key={id}
+      className={`flex gap-4 py-4 ${line.isOptimistic ? 'opacity-60' : ''}`}
+    >
+      {/* Product image */}
+      {image && (
+        <Link
+          prefetch="intent"
+          to={lineItemUrl}
+          onClick={() => layout === 'aside' && close()}
+          className="flex-shrink-0"
+        >
+          <div className="h-24 w-24 overflow-hidden rounded-lg border border-secondary-200 bg-secondary-50">
+            <Image
+              alt={title}
+              aspectRatio="1/1"
+              data={image}
+              height={96}
+              loading="lazy"
+              width={96}
+              className="h-full w-full object-cover object-center"
+            />
+          </div>
+        </Link>
+      )}
+
+      {/* Product details */}
+      <div className="flex flex-1 flex-col">
+        <div className="flex justify-between">
+          <div>
+            <Link
+              prefetch="intent"
+              to={lineItemUrl}
+              onClick={() => layout === 'aside' && close()}
+              className="text-sm font-medium text-secondary-900 hover:text-primary-600 transition-colors"
+            >
+              {product.title}
+            </Link>
+
+            {/* Selected options */}
+            {selectedOptions.length > 0 && (
+              <div className="mt-1 flex flex-wrap gap-x-2 text-xs text-secondary-500">
+                {selectedOptions.map((option) => (
+                  <span key={option.name}>
+                    {option.name}: {option.value}
+                  </span>
+                ))}
+              </div>
+            )}
+          </div>
+
+          {/* Price */}
+          <div className="ml-4 flex-shrink-0">
+            <ProductPrice price={line?.cost?.totalAmount} size="sm" />
+          </div>
+        </div>
+
+        {/* Quantity controls */}
+        <div className="mt-auto pt-2">
+          <CartLineQuantity line={line} />
+        </div>
+      </div>
+    </li>
+  );
+}
+
+/**
+ * Provides the controls to update the quantity of a line item in the cart.
+ * These controls are disabled when the line item is new, and the server
+ * hasn't yet responded that it was successfully added to the cart.
+ */
+function CartLineQuantity({line}: {line: CartLine}) {
+  if (!line || typeof line?.quantity === 'undefined') return null;
+  const {id: lineId, quantity, isOptimistic} = line;
+  const prevQuantity = Number(Math.max(0, quantity - 1).toFixed(0));
+  const nextQuantity = Number((quantity + 1).toFixed(0));
+
+  return (
+    <div className="flex items-center justify-between">
+      {/* Quantity controls */}
+      <div className="flex items-center rounded-lg border border-secondary-200">
+        <CartLineUpdateButton lines={[{id: lineId, quantity: prevQuantity}]}>
+          <button
+            aria-label="Decrease quantity"
+            disabled={quantity <= 1 || !!isOptimistic}
+            name="decrease-quantity"
+            value={prevQuantity}
+            className="flex h-8 w-8 items-center justify-center text-secondary-600 transition-colors hover:bg-secondary-100 disabled:cursor-not-allowed disabled:opacity-50"
+          >
+            <svg
+              className="h-4 w-4"
+              fill="none"
+              stroke="currentColor"
+              viewBox="0 0 24 24"
+            >
+              <path
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                strokeWidth={2}
+                d="M20 12H4"
+              />
+            </svg>
+          </button>
+        </CartLineUpdateButton>
+
+        <span className="w-10 text-center text-sm font-medium text-secondary-900">
+          {quantity}
+        </span>
+
+        <CartLineUpdateButton lines={[{id: lineId, quantity: nextQuantity}]}>
+          <button
+            aria-label="Increase quantity"
+            name="increase-quantity"
+            value={nextQuantity}
+            disabled={!!isOptimistic}
+            className="flex h-8 w-8 items-center justify-center text-secondary-600 transition-colors hover:bg-secondary-100 disabled:cursor-not-allowed disabled:opacity-50"
+          >
+            <svg
+              className="h-4 w-4"
+              fill="none"
+              stroke="currentColor"
+              viewBox="0 0 24 24"
+            >
+              <path
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                strokeWidth={2}
+                d="M12 4v16m8-8H4"
+              />
+            </svg>
+          </button>
+        </CartLineUpdateButton>
+      </div>
+
+      {/* Remove button */}
+      <CartLineRemoveButton lineIds={[lineId]} disabled={!!isOptimistic} />
+    </div>
+  );
+}
+
+/**
+ * A button that removes a line item from the cart. It is disabled
+ * when the line item is new, and the server hasn't yet responded
+ * that it was successfully added to the cart.
+ */
+function CartLineRemoveButton({
+  lineIds,
+  disabled,
+}: {
+  lineIds: string[];
+  disabled: boolean;
+}) {
+  return (
+    <CartForm
+      fetcherKey={getUpdateKey(lineIds)}
+      route="/cart"
+      action={CartForm.ACTIONS.LinesRemove}
+      inputs={{lineIds}}
+    >
+      <button
+        disabled={disabled}
+        type="submit"
+        className="text-xs font-medium text-secondary-500 underline-offset-2 transition-colors hover:text-red-600 hover:underline disabled:cursor-not-allowed disabled:opacity-50"
+      >
+        Remove
+      </button>
+    </CartForm>
+  );
+}
+
+function CartLineUpdateButton({
+  children,
+  lines,
+}: {
+  children: React.ReactNode;
+  lines: CartLineUpdateInput[];
+}) {
+  const lineIds = lines.map((line) => line.id);
+
+  return (
+    <CartForm
+      fetcherKey={getUpdateKey(lineIds)}
+      route="/cart"
+      action={CartForm.ACTIONS.LinesUpdate}
+      inputs={{lines}}
+    >
+      {children}
+    </CartForm>
+  );
+}
+
+/**
+ * Returns a unique key for the update action. This is used to make sure actions modifying the same line
+ * items are not run concurrently, but cancel each other. For example, if the user clicks "Increase quantity"
+ * and "Decrease quantity" in rapid succession, the actions will cancel each other and only the last one will run.
+ * @param lineIds - line ids affected by the update
+ * @returns
+ */
+function getUpdateKey(lineIds: string[]) {
+  return [CartForm.ACTIONS.LinesUpdate, ...lineIds].join('-');
+}