Pilot — Production-ready Shopify Hydrogen theme

A lightning-fast, fully-customizable Shopify storefront built with Hydrogen, React Router 7, and Weaverse.

📚 Docs · 🚀 Live demo · 🎨 Customize in Weaverse Studio · 🗣 Slack community · 🐞 Report a bug

Pilot pairs a hand-tuned Hydrogen storefront (SSR, streaming, edge-ready) with Weaverse Studio, so developers keep full control of the code while merchants edit every page visually — no redeploys. It ships with the routes, sections, and integrations a real store needs on day one.

---

Quick start

Pick the path that fits you. All three end at a running storefront on http://localhost:3456.

Option A — Let your AI coding agent do it (fastest)

Pilot is built to be set up by an agent (Cursor, Claude Code, Codex, opencode, …). Add the Weaverse skills, then ask your agent to set up the project:

npx skills add Weaverse/shopify-hydrogen-skills

"Use the setup-weaverse-project skill to set up this Weaverse Hydrogen storefront."

The agent boots a live preview on the bundled demo store first (≈2 minutes, zero credentials), then helps you swap in your own store and project. See AI coding agent support below.

Option B — Weaverse Studio (no code)

1. Install the Weaverse Hydrogen Customizer from the Shopify App Store.
2. Create a new Hydrogen storefront in Weaverse and pick Pilot.
3. Follow the in-Studio instructions to initialize the project locally with @weaverse/cli.
4. Open Weaverse Studio and start customizing.

Option C — Clone and run it yourself

git clone https://github.com/weaverse/pilot my-storefront
cd my-storefront
rm -rf .github         # Pilot's internal workflows
cp .env.example .env   # ships working demo-store tokens + a demo WEAVERSE_PROJECT_ID
npm install
npm run dev            # → http://localhost:3456

.env.example contains a live demo store's tokens, so the storefront runs immediately. Swap in your own values (see Environment) when you're ready to make it yours.

Note

.github holds Pilot's own workflows (demo deploy, CI, code review), which fail without Weaverse's secrets. Remove it the same way if you used Use this template; connecting Oxygen later adds your own deploy workflow.

---

Requirements

• Node.js ≥ 22.12.0
• npm (the repo ships a package-lock.json)
• A Shopify store and the Weaverse app to customize visually and get a WEAVERSE_PROJECT_ID

---

AI coding agent support

Pilot is designed to be developed with an agent:

• AGENTS.md — committed to the repo with inline Weaverse component patterns, the schema/input-type reference, loader patterns, and common pitfalls. Cursor, Claude Code, Windsurf, Codex, and GitHub Copilot read it automatically.

• Weaverse MCP — give your agent first-class access to your Weaverse account (search the docs, list projects/pages, read a page as Portable Text, theme settings, locales) over the read-only Content API:

  npx -y @weaverse/mcp

  Docs search needs no key; account tools use WEAVERSE_API_KEY (account tools require @weaverse/mcp ≥ 2.2.0). Per-client setup (Cursor, Claude Code, Codex, opencode, VS Code, …): https://weaverse.io/docs/developer-tools/weaverse-mcp

• setup-weaverse-project skill — the demo-first onboarding flow used in Option A, from Weaverse/shopify-hydrogen-skills.

---

What's included

Stack

• Shopify Hydrogen on Oxygen, with the Shopify CLI
• React Router 7 — routing, SSR, and data loading
• TailwindCSS v4 + Radix UI + class-variance-authority
• TypeScript (strict) and GraphQL codegen
• Biome for linting/formatting
• Swiper carousels, Playwright E2E tests

Commerce features

• Customer Account API (OAuth-based login)
• Combined Listings and product bundles
• Predictive search, cart, markets/localization, SEO, and analytics
• Judge.me reviews, Klaviyo email, and Shopify Inbox chat (setup guide)

And every section is editable in Weaverse Studio — no redeploy to change content or layout.

---

Commands

npm run dev          # dev server + codegen on http://localhost:3456
npm run build        # production build (shopify hydrogen build --codegen)
npm run preview      # build, then preview the production bundle
npm run typecheck    # tsc --noEmit
npm run biome:fix    # lint + format (write)
npm run test         # unit tests (tests/unit, Playwright runner)

Run npm run biome:fix && npm run typecheck before committing.

---

Environment

The minimum variables needed to render a storefront (the rest are feature-complete extras):

Variable	Required	Source
SESSION_SECRET	yes	any random string
PUBLIC_STORE_DOMAIN	yes	Shopify (Hydrogen sales channel / Headless app)
PUBLIC_STOREFRONT_API_TOKEN	yes	Shopify (Hydrogen sales channel / Headless app)
WEAVERSE_PROJECT_ID	yes	Weaverse Studio (or the agent handshake)
SHOP_ID, customer-account, checkout, analytics, reviews	no	Shopify / integrations, add after first success

If your store is already linked to a Hydrogen channel, npx shopify hydrogen env pull fills these in. See .env.example for the full list.

---

Project structure

app/
├── components/   # Reusable UI components
├── sections/     # Weaverse sections (visually editable)
├── routes/       # React Router routes (locale-prefixed)
├── graphql/      # GraphQL queries & fragments
├── hooks/        # Shared React hooks
├── utils/        # Helpers
├── weaverse/     # Weaverse client, component registry, theme schema
└── .server/      # Server-only context (Hydrogen + Weaverse client)

Key config: react-router.config.ts, vite.config.ts, codegen.ts, biome.json, AGENTS.md.

---

Developer guide

Load page data in parallel

Every route loads Weaverse data alongside its Storefront queries with Promise.all():

// app/routes/home.tsx
import type { LoaderFunctionArgs } from 'react-router';

export async function loader({ context }: LoaderFunctionArgs) {
  const { storefront, weaverse } = context;
  const [weaverseData, { shop }] = await Promise.all([
    weaverse.loadPage({ type: 'INDEX' }),
    storefront.query(SHOP_QUERY),
  ]);
  return { weaverseData, shop };
}

context.weaverse is a WeaverseClient injected in app/.server/context.ts (new WeaverseClient({ ...hydrogenContext, request, cache, themeSchema, components })).

Render a page

// app/routes/home.tsx
import { WeaverseContent } from '~/weaverse';

export default function Homepage() {
  return <WeaverseContent />;
}

WeaverseContent wraps WeaverseHydrogenRoot from @weaverse/hydrogen with the project's component registry.

Installable mobile app (PWA)

Pilot can make the storefront installable as a home-screen app on iOS and Android — no app store, branded per merchant. Enable it in theme settings under Mobile app (PWA) and optionally upload a square app icon (512×512 PNG recommended; falls back to the Shopify brand logo).

• /manifest.webmanifest is generated from theme settings (app/routes/pwa/manifest.webmanifest.ts).
• A minimal service worker (public/sw.js) caches only hashed build assets and Shopify CDN images. HTML, cart, account, and checkout are never intercepted.
• iOS shows no install prompt, so an optional one-time hint banner explains Share → Add to Home Screen (app/components/pwa-install-hint.tsx).
• Push notifications are intentionally not included.

Use global theme settings

Theme settings load in root.tsx and are read anywhere with useThemeSettings:

import { useThemeSettings } from '@weaverse/hydrogen';

function Logo() {
  const { logo } = useThemeSettings();
  return <img src={logo} alt="Logo" />;
}

Create a section

Add a file under app/sections/, export a component (it must accept ref and extend HydrogenComponentProps) and a schema, then register it in app/weaverse/components.ts.

// app/sections/video/index.tsx
import { createSchema, type HydrogenComponentProps } from '@weaverse/hydrogen';

interface VideoProps extends HydrogenComponentProps {
  ref: React.Ref<HTMLElement>;
  heading: string;
  videoUrl: string;
}

export default function Video({ ref, heading, videoUrl, ...rest }: VideoProps) {
  return (
    <section ref={ref} {...rest}>
      <h2>{heading}</h2>
      <iframe src={videoUrl} title="Video" allowFullScreen />
    </section>
  );
}

export const schema = createSchema({
  type: 'video',
  title: 'Video',
  settings: [
    {
      group: 'Video',
      inputs: [
        { type: 'text', name: 'heading', label: 'Heading', defaultValue: 'Learn more' },
        { type: 'text', name: 'videoUrl', label: 'Video URL', defaultValue: 'https://www.youtube.com/embed/-akQyQN8rYM' },
      ],
    },
  ],
});

Need data from Shopify or a third-party API? Export a server-side loader from the section and read it via Component.props.loaderData:

import type { ComponentLoaderArgs } from '@weaverse/hydrogen';

export const loader = async ({ weaverse, data }: ComponentLoaderArgs) => {
  const result = await weaverse.storefront.query(HOMEPAGE_SEO_QUERY, {
    variables: { handle: data.collection?.handle || 'frontpage' },
  });
  return result.data;
};

// app/weaverse/components.ts
import * as Video from '~/sections/video';
export const components: HydrogenComponent[] = [/* …existing, */ Video];

Dev tools

• Storefront: http://localhost:3456
• GraphiQL: http://localhost:3456/graphiql
• Network inspector: http://localhost:3456/debug-network

---

Deployment

• Shopify Oxygen (recommended)
• Vercel

Note

Deploy fails with JavaScript heap out of memory (exit 134)?

The Oxygen build generates a server sourcemap (~4.6 MB here, roughly two thirds of the server output). On large storefronts that can push the CI runner past Node's default heap, and the deploy dies before uploading a complete build. The environment then serves HTML referencing assets that were never published, and the storefront renders blank.

Set SHOPIFY_HYDROGEN_FLAG_SOURCEMAP=false on the deploy step of the generated workflow (.github/workflows/oxygen-deployment-*.yml). Add NODE_OPTIONS too if it still OOMs:

- name: Build and Publish to Oxygen
  run: npx shopify hydrogen deploy
  env:
    SHOPIFY_HYDROGEN_DEPLOYMENT_TOKEN: ${{ secrets.OXYGEN_DEPLOYMENT_TOKEN_... }}
    SHOPIFY_HYDROGEN_FLAG_SOURCEMAP: "false"
    NODE_OPTIONS: --max-old-space-size=8192

This can't be fixed in vite.config.ts: the Shopify CLI passes sourcemap inline to Vite when it builds, and inline config overrides the config file. The CLI flag (or its --no-sourcemap equivalent) is the only lever the theme repo can document.

---

Who's using Pilot

These Shopify (Plus) brands run on Weaverse/Pilot in production:

• Huckleberry Roasters — award-winning Colorado coffee, ethically sourced since 2011.
• Bubble Goods — 2,000+ healthy foods from independent U.S. makers.
• Karma and Luck — lifestyle brand rooted in timeless traditions.
• Baltzar — curated menswear from world-renowned specialists.
• iROCKER — premium paddle boards and water gear.
• Roland (Brazil) — electronic musical instruments.
• Timothy London — premium British travel goods.
• Vasuma Eyewear — Stockholm eyewear inspired by the 50s–60s.

…and many more.

---

References

• Weaverse docs · Weaverse MCP
• Hydrogen · React Router 7
• Tailwind CSS v4 · Radix UI · Biome

Contributions welcome — see CONTRIBUTING.md. Licensed under MIT.

---

Let Weaverse & Pilot power your Shopify store with top-tier performance and unmatched customization. 🚀