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

components

graphql

hooks

routes

sections

styles

types

utils

weaverse

entry.client.tsx

entry.server.tsx

routes.ts

root.tsx

public

server.ts

vite.config.ts

react-router.config.ts

.env

Path	Purpose
`app/.server/`	Server-only modules (load context, root loaders)
`app/components/`	Reusable UI components
`app/graphql/`	GraphQL queries and fragments
`app/hooks/`	Custom React hooks
`app/routes/`	Application routes
`app/sections/`	Theme sections
`app/styles/`	Global styles and Tailwind CSS entry
`app/types/`	TypeScript definitions
`app/utils/`	Helper functions
`app/weaverse/`	Weaverse configuration
`app/routes.ts`	Route configuration
`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/react-router';
import type { WeaverseComponentProps } from '@weaverse/hydrogen/react-router';

interface HeroProps extends WeaverseComponentProps {
  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`

Builds the per-request app context, including the Weaverse client. Hydrogen 2026.10 has no createHydrogenContext(), so the theme creates the session, Storefront client and customer account itself:

import { WeaverseClient } from '@weaverse/hydrogen/react-router';
import { createCustomerAccount } from '~/.server/customer-account';
import { AppSession } from '~/.server/session';
import {
  createRequestStorefront,
  resolveRequestLocale,
} from '~/.server/storefront';
import { components } from '~/weaverse/components';
import { themeSchema } from '~/weaverse/schema.server';

export async function createAppContext(
  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 storefront = createRequestStorefront({ request, env, cache, waitUntil });
  const customerAccount = createCustomerAccount({ env, request, session, storefront });

  const weaverse = new WeaverseClient({
    storefront,
    locale: resolveRequestLocale(request),
    env,
    cache,
    waitUntil,
    request,
    customerAccount,
    themeSchema,
    components,
  });

  // A plain object: `server.ts` copies it onto React Router's context
  return { env, cache, waitUntil, session, storefront, customerAccount, weaverse };
}

export type AppContext = Awaited<ReturnType<typeof createAppContext>>;

`server.ts`

The Oxygen worker entry. It builds the app context, lets Hydrogen answer the routes it owns (/api/cart, /account/login, …), renders the app with React Router, and looks up Shopify URL redirects on a 404 — the Weaverse client itself is created in app/.server/context.ts:

import { handleShopifyRedirects, handleShopifyRoutes } from '@shopify/hydrogen';
import { createRequestHandler, RouterContextProvider } from 'react-router';
import * as serverBuild from 'virtual:react-router/server-build';
import { createAppContext } from '~/.server/context';
import { routeTemplates } from '~/utils/route-templates';

const handleRequest = createRequestHandler(serverBuild, process.env.NODE_ENV);

export default {
  async fetch(
    request: Request,
    env: Env,
    executionContext: ExecutionContext,
  ): Promise<Response> {
    const appContext = await createAppContext(request, env, executionContext);
    const { session, storefront } = appContext;
    const requestContext = storefront.requestContext;

    const shopifyRoute = handleShopifyRoutes({
      request,
      requestContext,
      sessionManager: session,
      storefrontClient: storefront,
      routeTemplates,
      handlers: [/* cart, predictive search and customer account handlers */],
    });
    if (shopifyRoute) {
      const response = await shopifyRoute;
      // ... commit the session
      return response;
    }

    const routerContext = Object.assign(new RouterContextProvider(), appContext);
    const response = await handleRequest(request, routerContext);

    if (response.status === 404) {
      const redirect = await handleShopifyRedirects({
        request,
        storefrontClient: storefront,
        routeTemplates,
      });
      if (redirect) return redirect;
    }

    // ... commit the session
    requestContext.applyResponseHeaders(response.headers);
    return response;
  },
};

See Step 3 of the v6 migration guide for the full file.

`entry.server.tsx`

Server-side rendering setup with React Router v7. The CSP header and nonce come from the theme’s own app/utils/csp.ts (see Content Security Policy):

import { isbot } from "isbot";
import { renderToReadableStream } from "react-dom/server";
import type { EntryContext, RouterContextProvider } from "react-router";
import { ServerRouter } from "react-router";
import {
  createContentSecurityPolicy,
  generateNonce,
  NonceProvider,
} from "~/utils/csp";
import { getWeaverseCsp } from "~/weaverse/csp";

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

  const body = await renderToReadableStream(
    <NonceProvider value={nonce}>
      <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 Promise.race([
      body.allReady,
      new Promise((resolve) => setTimeout(resolve, 2000)),
    ]);
  }

  responseHeaders.set("Content-Type", "text/html");
  responseHeaders.set("Content-Security-Policy-Report-Only", header);
  // ... Oxygen full-page cache headers

  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