hydrogen-forge 0.1.0

package/templates/starter/app/lib/orderFilters.ts

@@ -0,0 +1,90 @@
+/**
+ * Field name constants for order filtering
+ */
+export const ORDER_FILTER_FIELDS = {
+  NAME: 'name',
+  CONFIRMATION_NUMBER: 'confirmation_number',
+} as const;
+
+/**
+ * Parameters for filtering customer orders, see: https://shopify.dev/docs/api/customer/latest/queries/customer#returns-Customer.fields.orders.arguments.query
+ */
+export interface OrderFilterParams {
+  /** Order name or number (e.g., "#1001" or "1001") */
+  name?: string;
+  /** Order confirmation number */
+  confirmationNumber?: string;
+}
+
+/**
+ * Sanitizes a filter value to prevent injection attacks or malformed queries.
+ * Allows only alphanumeric characters, underscore, and dash.
+ * @param value - The input string to sanitize
+ * @returns The sanitized string
+ */
+function sanitizeFilterValue(value: string): string {
+  // Only allow alphanumeric, underscore, and dash
+  // Remove anything else to prevent injection
+  return value.replace(/[^a-zA-Z0-9_\-]/g, '');
+}
+
+/**
+ * Builds a query string for filtering customer orders using the Customer Account API
+ * @param filters - The filter parameters
+ * @returns A formatted query string for the GraphQL query parameter, or undefined if no filters
+ * @example
+ * buildOrderSearchQuery(\{ name: '1001' \}) // returns "name:1001"
+ * buildOrderSearchQuery(\{ name: '1001', confirmationNumber: 'ABC123' \}) // returns "name:1001 AND confirmation_number:ABC123"
+ */
+export function buildOrderSearchQuery(
+  filters: OrderFilterParams,
+): string | undefined {
+  const queryParts: string[] = [];
+
+  if (filters.name) {
+    // Remove # if present and trim
+    const cleanName = filters.name.replace(/^#/, '').trim();
+    const sanitizedName = sanitizeFilterValue(cleanName);
+    if (sanitizedName) {
+      queryParts.push(`name:${sanitizedName}`);
+    }
+  }
+
+  if (filters.confirmationNumber) {
+    const cleanConfirmation = filters.confirmationNumber.trim();
+    const sanitizedConfirmation = sanitizeFilterValue(cleanConfirmation);
+    if (sanitizedConfirmation) {
+      queryParts.push(`confirmation_number:${sanitizedConfirmation}`);
+    }
+  }
+
+  return queryParts.length > 0 ? queryParts.join(' AND ') : undefined;
+}
+
+/**
+ * Parses order filter parameters from URLSearchParams
+ * @param searchParams - The URL search parameters
+ * @returns Parsed filter parameters
+ * @example
+ * const url = new URL('https://example.com/orders?name=1001&confirmation_number=ABC123');
+ * parseOrderFilters(url.searchParams) // returns \{ name: '1001', confirmationNumber: 'ABC123' \}
+ */
+export function parseOrderFilters(
+  searchParams: URLSearchParams,
+): OrderFilterParams {
+  const filters: OrderFilterParams = {};
+
+  const name = searchParams.get(ORDER_FILTER_FIELDS.NAME);
+  if (name) {
+    filters.name = name;
+  }
+
+  const confirmationNumber = searchParams.get(
+    ORDER_FILTER_FIELDS.CONFIRMATION_NUMBER,
+  );
+  if (confirmationNumber) {
+    filters.confirmationNumber = confirmationNumber;
+  }
+
+  return filters;
+}

package/templates/starter/app/lib/redirect.ts

@@ -0,0 +1,23 @@
+import {redirect} from 'react-router';
+
+export function redirectIfHandleIsLocalized(
+  request: Request,
+  ...localizedResources: Array<{
+    handle: string;
+    data: {handle: string} & unknown;
+  }>
+) {
+  const url = new URL(request.url);
+  let shouldRedirect = false;
+
+  localizedResources.forEach(({handle, data}) => {
+    if (handle !== data.handle) {
+      url.pathname = url.pathname.replace(handle, data.handle);
+      shouldRedirect = true;
+    }
+  });
+
+  if (shouldRedirect) {
+    throw redirect(url.toString());
+  }
+}

package/templates/starter/app/lib/search.ts

@@ -0,0 +1,79 @@
+import type {
+  PredictiveSearchQuery,
+  RegularSearchQuery,
+} from 'storefrontapi.generated';
+
+type ResultWithItems<Type extends 'predictive' | 'regular', Items> = {
+  type: Type;
+  term: string;
+  error?: string;
+  result: {total: number; items: Items};
+};
+
+export type RegularSearchReturn = ResultWithItems<
+  'regular',
+  RegularSearchQuery
+>;
+export type PredictiveSearchReturn = ResultWithItems<
+  'predictive',
+  NonNullable<PredictiveSearchQuery['predictiveSearch']>
+>;
+
+/**
+ * Returns the empty state of a predictive search result to reset the search state.
+ */
+export function getEmptyPredictiveSearchResult(): PredictiveSearchReturn['result'] {
+  return {
+    total: 0,
+    items: {
+      articles: [],
+      collections: [],
+      products: [],
+      pages: [],
+      queries: [],
+    },
+  };
+}
+
+interface UrlWithTrackingParams {
+  /** The base URL to which the tracking parameters will be appended. */
+  baseUrl: string;
+  /** The trackingParams returned by the Storefront API. */
+  trackingParams?: string | null;
+  /** Any additional query parameters to be appended to the URL. */
+  params?: Record<string, string>;
+  /** The search term to be appended to the URL. */
+  term: string;
+}
+
+/**
+ * A utility function that appends tracking parameters to a URL. Tracking parameters are
+ * used internally by Shopify to enhance search results and admin dashboards.
+ * @example
+ * ```ts
+ * const baseUrl = 'www.example.com';
+ * const trackingParams = 'utm_source=shopify&utm_medium=shopify_app&utm_campaign=storefront';
+ * const params = { foo: 'bar' };
+ * const term = 'search term';
+ * const url = urlWithTrackingParams({ baseUrl, trackingParams, params, term });
+ * console.log(url);
+ * // Output: 'https://www.example.com?foo=bar&q=search%20term&utm_source=shopify&utm_medium=shopify_app&utm_campaign=storefront'
+ * ```
+ */
+export function urlWithTrackingParams({
+  baseUrl,
+  trackingParams,
+  params: extraParams,
+  term,
+}: UrlWithTrackingParams) {
+  let search = new URLSearchParams({
+    ...extraParams,
+    q: encodeURIComponent(term),
+  }).toString();
+
+  if (trackingParams) {
+    search = `${search}&${trackingParams}`;
+  }
+
+  return `${baseUrl}?${search}`;
+}

package/templates/starter/app/lib/session.ts

@@ -0,0 +1,72 @@
+import type {HydrogenSession} from '@shopify/hydrogen';
+import {
+  createCookieSessionStorage,
+  type SessionStorage,
+  type Session,
+} from 'react-router';
+
+/**
+ * This is a custom session implementation for your Hydrogen shop.
+ * Feel free to customize it to your needs, add helper methods, or
+ * swap out the cookie-based implementation with something else!
+ */
+export class AppSession implements HydrogenSession {
+  public isPending = false;
+
+  #sessionStorage;
+  #session;
+
+  constructor(sessionStorage: SessionStorage, session: Session) {
+    this.#sessionStorage = sessionStorage;
+    this.#session = session;
+  }
+
+  static async init(request: Request, secrets: string[]) {
+    const storage = createCookieSessionStorage({
+      cookie: {
+        name: 'session',
+        httpOnly: true,
+        path: '/',
+        sameSite: 'lax',
+        secrets,
+      },
+    });
+
+    const session = await storage
+      .getSession(request.headers.get('Cookie'))
+      .catch(() => storage.getSession());
+
+    return new this(storage, session);
+  }
+
+  get has() {
+    return this.#session.has;
+  }
+
+  get get() {
+    return this.#session.get;
+  }
+
+  get flash() {
+    return this.#session.flash;
+  }
+
+  get unset() {
+    this.isPending = true;
+    return this.#session.unset;
+  }
+
+  get set() {
+    this.isPending = true;
+    return this.#session.set;
+  }
+
+  destroy() {
+    return this.#sessionStorage.destroySession(this.#session);
+  }
+
+  commit() {
+    this.isPending = false;
+    return this.#sessionStorage.commitSession(this.#session);
+  }
+}

package/templates/starter/app/lib/variants.ts

@@ -0,0 +1,46 @@
+import {useLocation} from 'react-router';
+import type {SelectedOption} from '@shopify/hydrogen/storefront-api-types';
+import {useMemo} from 'react';
+
+export function useVariantUrl(
+  handle: string,
+  selectedOptions?: SelectedOption[],
+) {
+  const {pathname} = useLocation();
+
+  return useMemo(() => {
+    return getVariantUrl({
+      handle,
+      pathname,
+      searchParams: new URLSearchParams(),
+      selectedOptions,
+    });
+  }, [handle, selectedOptions, pathname]);
+}
+
+export function getVariantUrl({
+  handle,
+  pathname,
+  searchParams,
+  selectedOptions,
+}: {
+  handle: string;
+  pathname: string;
+  searchParams: URLSearchParams;
+  selectedOptions?: SelectedOption[];
+}) {
+  const match = /(\/[a-zA-Z]{2}-[a-zA-Z]{2}\/)/g.exec(pathname);
+  const isLocalePathname = match && match.length > 0;
+
+  const path = isLocalePathname
+    ? `${match![0]}products/${handle}`
+    : `/products/${handle}`;
+
+  selectedOptions?.forEach((option) => {
+    searchParams.set(option.name, option.value);
+  });
+
+  const searchString = searchParams.toString();
+
+  return path + (searchString ? '?' + searchParams.toString() : '');
+}

package/templates/starter/app/root.tsx

@@ -0,0 +1,209 @@
+import {Analytics, getShopAnalytics, useNonce} from '@shopify/hydrogen';
+import {
+  Outlet,
+  useRouteError,
+  isRouteErrorResponse,
+  type ShouldRevalidateFunction,
+  Links,
+  Meta,
+  Scripts,
+  ScrollRestoration,
+  useRouteLoaderData,
+} from 'react-router';
+import type {Route} from './+types/root';
+import favicon from '~/assets/favicon.svg';
+import {FOOTER_QUERY, HEADER_QUERY} from '~/lib/fragments';
+import resetStyles from '~/styles/reset.css?url';
+import tailwindStyles from '~/styles/tailwind.css?url';
+import {PageLayout} from './components/PageLayout';
+
+export type RootLoader = typeof loader;
+
+/**
+ * This is important to avoid re-fetching root queries on sub-navigations
+ */
+export const shouldRevalidate: ShouldRevalidateFunction = ({
+  formMethod,
+  currentUrl,
+  nextUrl,
+}) => {
+  // revalidate when a mutation is performed e.g add to cart, login...
+  if (formMethod && formMethod !== 'GET') return true;
+
+  // revalidate when manually revalidating via useRevalidator
+  if (currentUrl.toString() === nextUrl.toString()) return true;
+
+  // Defaulting to no revalidation for root loader data to improve performance.
+  // When using this feature, you risk your UI getting out of sync with your server.
+  // Use with caution. If you are uncomfortable with this optimization, update the
+  // line below to `return defaultShouldRevalidate` instead.
+  // For more details see: https://remix.run/docs/en/main/route/should-revalidate
+  return false;
+};
+
+/**
+ * The main and reset stylesheets are added in the Layout component
+ * to prevent a bug in development HMR updates.
+ *
+ * This avoids the "failed to execute 'insertBefore' on 'Node'" error
+ * that occurs after editing and navigating to another page.
+ *
+ * It's a temporary fix until the issue is resolved.
+ * https://github.com/remix-run/remix/issues/9242
+ */
+export function links() {
+  return [
+    {
+      rel: 'preconnect',
+      href: 'https://cdn.shopify.com',
+    },
+    {
+      rel: 'preconnect',
+      href: 'https://shop.app',
+    },
+    {rel: 'icon', type: 'image/svg+xml', href: favicon},
+  ];
+}
+
+export async function loader(args: Route.LoaderArgs) {
+  // Start fetching non-critical data without blocking time to first byte
+  const deferredData = loadDeferredData(args);
+
+  // Await the critical data required to render initial state of the page
+  const criticalData = await loadCriticalData(args);
+
+  const {storefront, env} = args.context;
+
+  return {
+    ...deferredData,
+    ...criticalData,
+    publicStoreDomain: env.PUBLIC_STORE_DOMAIN,
+    shop: getShopAnalytics({
+      storefront,
+      publicStorefrontId: env.PUBLIC_STOREFRONT_ID,
+    }),
+    consent: {
+      checkoutDomain: env.PUBLIC_CHECKOUT_DOMAIN,
+      storefrontAccessToken: env.PUBLIC_STOREFRONT_API_TOKEN,
+      withPrivacyBanner: false,
+      // localize the privacy banner
+      country: args.context.storefront.i18n.country,
+      language: args.context.storefront.i18n.language,
+    },
+  };
+}
+
+/**
+ * Load data necessary for rendering content above the fold. This is the critical data
+ * needed to render the page. If it's unavailable, the whole page should 400 or 500 error.
+ */
+async function loadCriticalData({context}: Route.LoaderArgs) {
+  const {storefront} = context;
+
+  const [header] = await Promise.all([
+    storefront.query(HEADER_QUERY, {
+      cache: storefront.CacheLong(),
+      variables: {
+        headerMenuHandle: 'main-menu', // Adjust to your header menu handle
+      },
+    }),
+    // Add other queries here, so that they are loaded in parallel
+  ]);
+
+  return {header};
+}
+
+/**
+ * Load data for rendering content below the fold. This data is deferred and will be
+ * fetched after the initial page load. If it's unavailable, the page should still 200.
+ * Make sure to not throw any errors here, as it will cause the page to 500.
+ */
+function loadDeferredData({context}: Route.LoaderArgs) {
+  const {storefront, customerAccount, cart} = context;
+
+  // defer the footer query (below the fold)
+  const footer = storefront
+    .query(FOOTER_QUERY, {
+      cache: storefront.CacheLong(),
+      variables: {
+        footerMenuHandle: 'footer', // Adjust to your footer menu handle
+      },
+    })
+    .catch((error: Error) => {
+      // Log query errors, but don't throw them so the page can still render
+      console.error(error);
+      return null;
+    });
+  return {
+    cart: cart.get(),
+    isLoggedIn: customerAccount.isLoggedIn(),
+    footer,
+  };
+}
+
+export function Layout({children}: {children?: React.ReactNode}) {
+  const nonce = useNonce();
+
+  return (
+    <html lang="en">
+      <head>
+        <meta charSet="utf-8" />
+        <meta name="viewport" content="width=device-width,initial-scale=1" />
+        <link rel="stylesheet" href={resetStyles}></link>
+        <link rel="stylesheet" href={tailwindStyles}></link>
+        <Meta />
+        <Links />
+      </head>
+      <body>
+        {children}
+        <ScrollRestoration nonce={nonce} />
+        <Scripts nonce={nonce} />
+      </body>
+    </html>
+  );
+}
+
+export default function App() {
+  const data = useRouteLoaderData<RootLoader>('root');
+
+  if (!data) {
+    return <Outlet />;
+  }
+
+  return (
+    <Analytics.Provider
+      cart={data.cart}
+      shop={data.shop}
+      consent={data.consent}
+    >
+      <PageLayout {...data}>
+        <Outlet />
+      </PageLayout>
+    </Analytics.Provider>
+  );
+}
+
+export function ErrorBoundary() {
+  const error = useRouteError();
+  let errorMessage = 'Unknown error';
+  let errorStatus = 500;
+
+  if (isRouteErrorResponse(error)) {
+    errorMessage = error?.data?.message ?? error.data;
+    errorStatus = error.status;
+  } else if (error instanceof Error) {
+    errorMessage = error.message;
+  }
+
+  return (
+    <div className="route-error">
+      <h1>Oops</h1>
+      <h2>{errorStatus}</h2>
+      {errorMessage && (
+        <fieldset>
+          <pre>{errorMessage}</pre>
+        </fieldset>
+      )}
+    </div>
+  );
+}

package/templates/starter/app/routes/$.tsx

@@ -0,0 +1,11 @@
+import type {Route} from './+types/$';
+
+export async function loader({request}: Route.LoaderArgs) {
+  throw new Response(`${new URL(request.url).pathname} not found`, {
+    status: 404,
+  });
+}
+
+export default function CatchAllPage() {
+  return null;
+}

package/templates/starter/app/routes/[robots.txt].tsx

@@ -0,0 +1,117 @@
+import type {Route} from './+types/[robots.txt]';
+import {parseGid} from '@shopify/hydrogen';
+
+export async function loader({request, context}: Route.LoaderArgs) {
+  const url = new URL(request.url);
+
+  const {shop} = await context.storefront.query(ROBOTS_QUERY);
+
+  const shopId = parseGid(shop.id).id;
+  const body = robotsTxtData({url: url.origin, shopId});
+
+  return new Response(body, {
+    status: 200,
+    headers: {
+      'Content-Type': 'text/plain',
+
+      'Cache-Control': `max-age=${60 * 60 * 24}`,
+    },
+  });
+}
+
+function robotsTxtData({url, shopId}: {shopId?: string; url?: string}) {
+  const sitemapUrl = url ? `${url}/sitemap.xml` : undefined;
+
+  return `
+User-agent: *
+${generalDisallowRules({sitemapUrl, shopId})}
+
+# Google adsbot ignores robots.txt unless specifically named!
+User-agent: adsbot-google
+Disallow: /checkouts/
+Disallow: /checkout
+Disallow: /carts
+Disallow: /orders
+${shopId ? `Disallow: /${shopId}/checkouts` : ''}
+${shopId ? `Disallow: /${shopId}/orders` : ''}
+Disallow: /*?*oseid=*
+Disallow: /*preview_theme_id*
+Disallow: /*preview_script_id*
+
+User-agent: Nutch
+Disallow: /
+
+User-agent: AhrefsBot
+Crawl-delay: 10
+${generalDisallowRules({sitemapUrl, shopId})}
+
+User-agent: AhrefsSiteAudit
+Crawl-delay: 10
+${generalDisallowRules({sitemapUrl, shopId})}
+
+User-agent: MJ12bot
+Crawl-Delay: 10
+
+User-agent: Pinterest
+Crawl-delay: 1
+`.trim();
+}
+
+/**
+ * This function generates disallow rules that generally follow what Shopify's
+ * Online Store has as defaults for their robots.txt
+ */
+function generalDisallowRules({
+  shopId,
+  sitemapUrl,
+}: {
+  shopId?: string;
+  sitemapUrl?: string;
+}) {
+  return `Disallow: /admin
+Disallow: /cart
+Disallow: /orders
+Disallow: /checkouts/
+Disallow: /checkout
+${shopId ? `Disallow: /${shopId}/checkouts` : ''}
+${shopId ? `Disallow: /${shopId}/orders` : ''}
+Disallow: /carts
+Disallow: /account
+Disallow: /collections/*sort_by*
+Disallow: /*/collections/*sort_by*
+Disallow: /collections/*+*
+Disallow: /collections/*%2B*
+Disallow: /collections/*%2b*
+Disallow: /*/collections/*+*
+Disallow: /*/collections/*%2B*
+Disallow: /*/collections/*%2b*
+Disallow: */collections/*filter*&*filter*
+Disallow: /blogs/*+*
+Disallow: /blogs/*%2B*
+Disallow: /blogs/*%2b*
+Disallow: /*/blogs/*+*
+Disallow: /*/blogs/*%2B*
+Disallow: /*/blogs/*%2b*
+Disallow: /*?*oseid=*
+Disallow: /*preview_theme_id*
+Disallow: /*preview_script_id*
+Disallow: /policies/
+Disallow: /*/*?*ls=*&ls=*
+Disallow: /*/*?*ls%3D*%3Fls%3D*
+Disallow: /*/*?*ls%3d*%3fls%3d*
+Disallow: /search
+Allow: /search/
+Disallow: /search/?*
+Disallow: /apple-app-site-association
+Disallow: /.well-known/shopify/monorail
+${sitemapUrl ? `Sitemap: ${sitemapUrl}` : ''}`;
+}
+
+const ROBOTS_QUERY = `#graphql
+  query StoreRobots($country: CountryCode, $language: LanguageCode)
+   @inContext(country: $country, language: $language) {
+    shop {
+      id
+    }
+  }
+` as const;

package/templates/starter/app/routes/[sitemap.xml].tsx

@@ -0,0 +1,16 @@
+import type {Route} from './+types/[sitemap.xml]';
+import {getSitemapIndex} from '@shopify/hydrogen';
+
+export async function loader({
+  request,
+  context: {storefront},
+}: Route.LoaderArgs) {
+  const response = await getSitemapIndex({
+    storefront,
+    request,
+  });
+
+  response.headers.set('Cache-Control', `max-age=${60 * 60 * 24}`);
+
+  return response;
+}