PR4 - Migrate skeleton template to React Router 7.8.x

[juanpprieto]

WHY are these changes introduced?

Part of the React Router 7.8.x migration effort. This PR migrates the skeleton template to use React Router 7.8.x, showcasing the power of the new framework features and Hydrogen's enhanced support for React Router best practices.

WHAT is this pull request doing?

This PR migrates the skeleton template to React Router 7.8.x, leveraging the new Hydrogen exports and React Router's advanced type safety features.

🚀 Key Highlights

1. Hydrogen Preset for Zero-Config Setup

The new hydrogenPreset from @shopify/hydrogen provides automatic configuration for Hydrogen apps:

// react-router.config.ts
import {hydrogenPreset} from '@shopify/hydrogen/react-router-preset';
import type {Config} from '@react-router/dev/config';

export default {
  presets: [hydrogenPreset()],
} satisfies Config;

2. Enhanced Type Safety with Automatic Type Generation

React Router 7.8.x provides automatic type generation for every route, eliminating type errors and providing perfect IntelliSense:

Before (Manual typing with potential errors):

// app/routes/products.$handle.tsx
import {defer, type LoaderFunctionArgs} from '@shopify/remix-oxygen';
import {useLoaderData, type MetaFunction} from '@remix-run/react';

// Manual typing - prone to errors and drift
export const meta: MetaFunction<typeof loader> = ({data}) => {
  // TypeScript can't verify this matches actual loader return
  return [{title: data?.product?.title}];
};

export async function loader({params, context}: LoaderFunctionArgs) {
  // params types are generic, not route-specific
  const handle = params.handle; // string | undefined
  // ...
}

After (Automatic type safety with generated Route types):

// app/routes/products.$handle.tsx
import {defer} from '@shopify/remix-oxygen';
import {useLoaderData} from 'react-router';
import type {Route} from './+types/products.$handle';  // ← Auto-generated types!

// Type-safe meta with auto-completion for loader data
export const meta: Route.MetaFunction = ({data}) => {
  // TypeScript knows exactly what data contains
  return [{title: data?.product?.title}];
};

export async function loader({params, context}: Route.LoaderArgs) {
  // params.handle is typed as string (required param)
  const handle = params.handle; // string - never undefined!
  // Full type safety for context from HydrogenContext
  const {storefront, cart, env} = context;
  // ...
}

export default function Component() {
  // Automatically typed from loader return
  const {product, variants} = useLoaderData<typeof loader>();
  // Full IntelliSense for all properties
  return <div>{product.title}</div>;
}

Key Pattern: Every route imports its auto-generated types:

// Standard import pattern for all routes
import type {Route} from './+types/[route-name]';

// Then use Route.* for all exports
export const meta: Route.MetaFunction = () => {};
export const links: Route.LinksFunction = () => [];
export const headers: Route.HeadersFunction = () => {};
export async function loader(args: Route.LoaderArgs) {}
export async function action(args: Route.ActionArgs) {}

3. New Server Entry with Hydrogen's createRequestHandler

The server.ts now imports createRequestHandler from @shopify/hydrogen/oxygen and uses React Router's virtual build import:

Before (Remix-specific imports):

// server.ts
import {createRequestHandler} from '@shopify/remix-oxygen';
import {createAppLoadContext} from '~/lib/context';

export default {
  async fetch(request, env, executionContext) {
    const appLoadContext = await createAppLoadContext(
      request,
      env,
      executionContext,
    );

    const handleRequest = createRequestHandler({
      build: await import(/* @vite-ignore */ './build/server/index.js'),
      mode: process.env.NODE_ENV,
      getLoadContext: () => appLoadContext,
    });

    const response = await handleRequest(request);
    // ... handle session and redirects
    return response;
  },
};

After (Hydrogen/React Router 7.8.x imports):

// server.ts
import {createRequestHandler} from '@shopify/hydrogen/oxygen';  // ← New import!
import {createHydrogenRouterContext} from '~/lib/context';

export default {
  async fetch(request, env, executionContext) {
    const hydrogenContext = await createHydrogenRouterContext(
      request,
      env,
      executionContext,
    );

    const handleRequest = createRequestHandler({
      // React Router 7.8.x uses virtual imports for the server build
      build: await import('virtual:react-router/server-build'),
      mode: process.env.NODE_ENV,
      getLoadContext: () => hydrogenContext,
    });

    const response = await handleRequest(request);
    
    // Handle session commits
    if (hydrogenContext.session.isPending) {
      response.headers.set(
        'Set-Cookie',
        await hydrogenContext.session.commit(),
      );
    }
    
    // Handle storefront redirects
    return storefrontRedirect({
      request,
      response,
      storefront: hydrogenContext.storefront,
    });
  },
};

Key changes:

• Import changed from @shopify/remix-oxygen to @shopify/hydrogen/oxygen
• Build import changed from './build/server/index.js' to 'virtual:react-router/server-build'
• Context renamed from createAppLoadContext to createHydrogenRouterContext

4. New Hydrogen Context Exports

Implement the new @shopify/hydrogen exports for React Router integration:

import {
  createHydrogenContext,     // Create typed context for routes
  hydrogenPreset,            // Zero-config React Router preset
  //...
} from '@shopify/hydrogen';

import {
  createRequestHandler,       // Server request handler for Oxygen
} from '@shopify/hydrogen/oxygen';

5. Simplified Context Creation

The new createHydrogenContext provides a streamlined way to set up the app context:

// app/lib/context.ts
import {createHydrogenContext} from '@shopify/hydrogen';
import {AppSession} from '~/lib/session';

// Define the additional context object
const additionalContext = {
  // Additional context for custom properties, CMS clients, 3P SDKs, etc.
  // These will be available as both context.propertyName and context.get(propertyContext)
  // Example of complex objects that could be added:
  // cms: await createCMSClient(env),
} as const;

// Automatically augment HydrogenAdditionalContext with the additional context type
type AdditionalContextType = typeof additionalContext;

declare global {
  interface HydrogenAdditionalContext extends AdditionalContextType {}
}

/**
 * Creates Hydrogen context for React Router 7.8.x
 * Returns HydrogenRouterContextProvider with hybrid access patterns
 * */
export async function createHydrogenRouterContext(request,env,executionContext) {
  // ..existing code
  
  const hydrogenContext = createHydrogenContext(
    {
      env,
      request,
      cache,
      waitUntil,
      session,
      // Or detect from URL path based on locale subpath, cookies, or any other strategy
      i18n: {language: 'EN', country: 'US'},
      cart: {
        queryFragment: CART_QUERY_FRAGMENT,
      },
    },
    additionalContext,
  );

  return hydrogenContext;
}

6. Type-Safe Route Patterns

Every route now follows a consistent, type-safe pattern with auto-generated types:

// Example: app/routes/collections.$handle.tsx
import {useLoaderData} from 'react-router';
import type {Route} from './+types/collections.$handle';  // ← Auto-generated!

export const meta: Route.MetaFunction = ({data}) => {
  // data is fully typed based on loader return
  return [{title: `Collection: ${data?.collection.title ?? ''}`}];
};

export async function loader({params, context}: Route.LoaderArgs) {
  // params.handle is string (not string | undefined)
  const {handle} = params;
  const {storefront} = context;
  // ...
}

export default function Collection() {
  const {collection} = useLoaderData<typeof loader>();
  // Full type safety and IntelliSense
  return <h1>{collection.title}</h1>;
}

HOW to test your changes?

1. Setup:

   git checkout feat/skeleton-rr-7.8
   npm install && npm run build:pkg
   cd templates/skeleton && npm install

2. Verify all scripts pass:

   npm run build      # ✅ Builds with React Router 7.8.x
   npm run typecheck  # ✅ Types are generated and valid
   npm run lint       # ✅ Code follows best practices
   npm run dev        # ✅ Dev server with all Hydrogen features

3. Test type generation:

   # Check generated types
   ls app/routes/+types/
   # Modify a route and see types auto-update
   npm run typecheck

4. Verify Hydrogen features:

   • GraphiQL: http://localhost:3000/graphiql
   • Subrequest Profiler: http://localhost:3000/subrequest-profiler
   • All routes load with proper typing

Checklist

• I've read the Contributing Guidelines
• I've considered possible cross-platform impacts (Mac, Linux, Windows)
• I've added a changeset if this PR contains user-facing or noteworthy changes
• I've added tests to cover my changes
• I've added or updated the documentation

[shopify]

Oxygen deployed a preview of your feat/skeleton-rr-7.8 branch. Details:

Storefront	Status	Preview link	Deployment details	Last update (UTC)
metaobjects	✅ Successful (Logs)	Preview deployment	Inspect deployment	September 5, 2025 5:31 AM
Skeleton (skeleton.hydrogen.shop)	✅ Successful (Logs)	Preview deployment	Inspect deployment	September 13, 2025 3:11 AM
custom-cart-method	- (Logs)	-	Inspect deployment	September 5, 2025 5:31 AM
third-party-queries-caching	- (Logs)	-	Inspect deployment	September 5, 2025 5:31 AM

Learn more about Hydrogen's GitHub integration.