Project Structure

Overview

The Weaverse Hydrogen theme follows a modern Shopify Hydrogen structure, optimized for performance and developer experience. Let’s explore the key components of your theme.

Core Structure

🌳 my-theme
├── 📁 app/
│   ├── 📁 .server/            # Server-only modules (load context, root loaders)
│   ├── 📁 components/         # Reusable UI components
│   ├── 📁 graphql/            # GraphQL queries and fragments
│   ├── 📁 hooks/              # Custom React hooks
│   ├── 📁 routes/             # Application routes
│   ├── 📁 sections/           # Theme sections
│   ├── 📁 styles/             # Global styles and Tailwind CSS entry
│   ├── 📁 types/              # TypeScript definitions
│   ├── 📁 utils/              # Helper functions
│   ├── 📁 weaverse/           # Weaverse configuration
│   ├── 📄 entry.client.tsx
│   ├── 📄 entry.server.tsx
│   ├── 📄 routes.ts           # Route configuration
│   └── 📄 root.tsx
├── 📁 public/                 # Static assets
├── 📄 server.ts               # Oxygen request handler
├── 📄 vite.config.ts          # Build configuration (includes the Tailwind v4 plugin)
├── 📄 react-router.config.ts  # React Router configuration
└── 📄 .env                    # Environment variables

Key Directories

`/app/components`

Reusable UI components:

// 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>
  );
}

`/app/sections`

Theme sections for Weaverse Studio:

// 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' },
      ],
    },
  ],
});

`/app/weaverse`

Core Weaverse configuration files:

components.ts - Component registry (the components array passed to WeaverseClient)
schema.server.ts - Theme schema
index.tsx - WeaverseContent renderer and page-data validation
style.tsx - Global styles generated from theme settings
csp.ts - Content Security Policy directives for Studio

Essential Files

`app/.server/context.ts`

Creates the Hydrogen router context and attaches the Weaverse client to it:

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;
}

`server.ts`

The Oxygen request handler. It builds the context and hands it to React Router — the Weaverse client itself is created in app/.server/context.ts:

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;
  },
};

`entry.server.tsx`

Server-side rendering setup with React Router v7:

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,
  });
}

`.env`

Required environment variables:

# 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

Development Commands

# Install dependencies
npm install

# Start development
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview

Next Steps

Development Guide - Build custom components and sections
API Reference - Learn about Weaverse APIs and utilities
Deployment - Deploy your theme to production

Need help? Check our Community or FAQ.

Introduction

Studio Guide

Project Structure

Overview

Core Structure

Key Directories

`/app/components`

`/app/sections`

`/app/weaverse`

Essential Files

`app/.server/context.ts`

`server.ts`

`entry.server.tsx`

`.env`

Development Commands

Next Steps

​Overview

​Core Structure

​Key Directories

​/app/components

​/app/sections

​/app/weaverse

​Essential Files

​app/.server/context.ts

​server.ts

​entry.server.tsx

​.env

​Development Commands

​Next Steps

Overview

Core Structure

Key Directories

`/app/components`

`/app/sections`

`/app/weaverse`

Essential Files

`app/.server/context.ts`

`server.ts`

`entry.server.tsx`

`.env`

Development Commands

Next Steps