Project Structure

// Example: app/components/Button.tsx
export function Button({ children, className = '', ...props }) {
  return (
    <button 
      className={`px-4 py-2 bg-primary text-white ${className}`} 
      {...props}
    >
      {children}
    </button>
  );
}

// Example: app/sections/hero/index.tsx
import { createSchema } from '@weaverse/hydrogen';
import type { HydrogenComponentProps } from '@weaverse/hydrogen';

interface HeroProps extends HydrogenComponentProps {
  heading: string;
  description: string;
}

function Hero(props: HeroProps) {
  const { heading, description, className, ...rest } = props;

  return (
    <section
      {...rest}
      className={`py-12 px-4 max-w-7xl mx-auto ${className || ''}`}
    >
      <div className="text-center">
        <h1 className="text-4xl font-bold tracking-tight sm:text-6xl">
          {heading}
        </h1>
        <p className="mt-6 text-lg leading-8 text-gray-600">
          {description}
        </p>
      </div>
    </section>
  );
}

export default Hero;

export const schema = createSchema({
  type: 'hero',
  title: 'Hero',
  settings: [
    {
      group: 'Content',
      inputs: [
        { type: 'text', name: 'heading', label: 'Heading' },
        { type: 'textarea', name: 'description', label: 'Description' },
      ],
    },
  ],
});

import { createHydrogenContext } from '@shopify/hydrogen';
import { WeaverseClient } from '@weaverse/hydrogen';
import {
  CART_MUTATION_FRAGMENT,
  CART_QUERY_FRAGMENT,
} from '~/graphql/fragments';
import { components } from '~/weaverse/components';
import { themeSchema } from '~/weaverse/schema.server';

export async function createHydrogenRouterContext(
  request: Request,
  env: Env,
  executionContext: ExecutionContext,
) {
  const waitUntil = executionContext.waitUntil.bind(executionContext);
  const [cache, session] = await Promise.all([
    caches.open('hydrogen'),
    AppSession.init(request, [env.SESSION_SECRET]),
  ]);

  const hydrogenContext = createHydrogenContext({
    env,
    request,
    cache,
    waitUntil,
    session,
    i18n: getLocaleFromRequest(request),
    cart: {
      queryFragment: CART_QUERY_FRAGMENT,
      mutateFragment: CART_MUTATION_FRAGMENT,
    },
  });

  const weaverse = new WeaverseClient({
    ...hydrogenContext,
    request,
    cache,
    themeSchema,
    components,
  });

  // Add weaverse directly to the hydrogenContext instance.
  // This preserves the RouterContextProvider class instance — do not
  // return a spread copy such as `{ ...hydrogenContext, weaverse }`.
  Object.assign(hydrogenContext, { weaverse });

  return hydrogenContext;
}

import * as remixBuild from 'virtual:react-router/server-build';
import { storefrontRedirect } from '@shopify/hydrogen';
import { createRequestHandler } from '@shopify/hydrogen/oxygen';
import { createHydrogenRouterContext } from '~/.server/context';

export default {
  async fetch(
    request: Request,
    env: Env,
    executionContext: ExecutionContext,
  ): Promise<Response> {
    const hydrogenContext = await createHydrogenRouterContext(
      request,
      env,
      executionContext,
    );

    const handleRequest = createRequestHandler({
      build: remixBuild,
      mode: process.env.NODE_ENV,
      getLoadContext: () => hydrogenContext,
    });

    const response = await handleRequest(request);

    if (response.status === 404) {
      return storefrontRedirect({
        request,
        response,
        storefront: hydrogenContext.storefront,
      });
    }

    return response;
  },
};

import { ServerRouter, type EntryContext } from "react-router";
import {
  createContentSecurityPolicy,
  type HydrogenRouterContextProvider,
} from "@shopify/hydrogen";
import { isbot } from "isbot";
import { renderToReadableStream } from "react-dom/server";
import { getWeaverseCsp } from "~/weaverse/csp";

export default async function handleRequest(
  request: Request,
  responseStatusCode: number,
  responseHeaders: Headers,
  reactRouterContext: EntryContext,
  context: HydrogenRouterContextProvider,
) {
  const { nonce, header, NonceProvider } = createContentSecurityPolicy({
    ...getWeaverseCsp(request, context),
    shop: {
      checkoutDomain: context.env?.PUBLIC_CHECKOUT_DOMAIN || context.env?.PUBLIC_STORE_DOMAIN,
      storeDomain: context.env?.PUBLIC_STORE_DOMAIN,
    },
  });

  const body = await renderToReadableStream(
    <NonceProvider>
      <ServerRouter context={reactRouterContext} url={request.url} nonce={nonce} />
    </NonceProvider>,
    {
      nonce,
      signal: request.signal,
      onError(error) {
        console.error(error);
        responseStatusCode = 500;
      },
    },
  );

  if (isbot(request.headers.get("user-agent"))) {
    await body.allReady;
  }

  responseHeaders.set("Content-Type", "text/html");
  responseHeaders.set("Content-Security-Policy-Report-Only", header);

  return new Response(body, {
    headers: responseHeaders,
    status: responseStatusCode,
  });
}

# Core Configuration
SESSION_SECRET="<generated-random-secret>"

# Shopify Configuration
PUBLIC_STORE_DOMAIN=your-store.myshopify.com
PUBLIC_STOREFRONT_API_TOKEN=your-token
PUBLIC_CUSTOMER_ACCOUNT_API_CLIENT_ID=your-client-id
SHOP_ID=your-shop-id
PUBLIC_CHECKOUT_DOMAIN=your-checkout-domain

# Optional Shopify Configuration
PUBLIC_STOREFRONT_ID=your-storefront-id
# PRIVATE_STOREFRONT_API_TOKEN=your-private-token

# Weaverse Configuration
WEAVERSE_PROJECT_ID=your-project-id
# WEAVERSE_API_KEY=your-api-key

# Additional Services (Optional)
# PUBLIC_GOOGLE_GTM_ID=your-gtm-id
# JUDGEME_PRIVATE_API_TOKEN=your-judgeme-token
# ALI_REVIEWS_API_KEY=your-ali-reviews-key

# Custom Metafields & Metaobjects
METAOBJECT_COLORS_TYPE=shopify--color-pattern
CUSTOM_COLLECTION_BANNER_METAFIELD=custom.collection_banner

# Shopify Inbox (Optional)
# PUBLIC_SHOPIFY_INBOX_SHOP_ID=your-inbox-shop-id

# Install dependencies
npm install

# Start development
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview