Pilot — Production-ready Shopify Hydrogen theme
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
bash
"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)
- Install the Weaverse Hydrogen Customizer from the Shopify App Store.
- Create a new Hydrogen storefront in Weaverse and pick Pilot.
- Follow the in-Studio instructions to initialize the project locally with
@weaverse/cli.
- 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
cp .env.example .env # ships working demo-store tokens + a demo WEAVERSE_PROJECT_ID
npm install
npm run dev # → http://localhost:3456
bash.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.
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:
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
Commerce features
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)
bashRun 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)
typescriptKey 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():
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 };
}
tsxcontext.weaverse is a WeaverseClient injected in app/.server/context.ts (new WeaverseClient({ ...hydrogenContext, request, cache, themeSchema, components })).
Render a page
import { WeaverseContent } from '~/weaverse';
export default function Homepage() {
return <WeaverseContent />;
}
tsxWeaverseContent 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" />;
}
tsxCreate 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.
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' },
],
},
],
});
tsxNeed 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;
};
tsx
import * as Video from '~/sections/video';
export const components: HydrogenComponent[] = [ Video];
tsDev tools
Deployment
[!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
yamlThis 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:
…and many more.
References
Contributions welcome — see CONTRIBUTING.md. Licensed under MIT.
Let Weaverse & Pilot power your Shopify store with top-tier performance and unmatched customization. 🚀
![shopify[bot]](https://avatars.githubusercontent.com/in/101950?v=4){kind=small}
