{"id":26509773,"url":"https://github.com/weaverse/pilot","last_synced_at":"2026-05-04T12:06:43.618Z","repository":{"id":161013677,"uuid":"631863530","full_name":"Weaverse/pilot","owner":"Weaverse","description":"Pilot - Shopify Hydrogen Theme, power by Weaverse Hydrogen Theme Customizer.","archived":false,"fork":false,"pushed_at":"2024-04-12T05:42:03.000Z","size":2162,"stargazers_count":60,"open_issues_count":0,"forks_count":5,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-04-13T13:02:18.892Z","etag":null,"topics":["headless-commerce","hydrogen","remix","shopify-hydrogen","shopify-storefront"],"latest_commit_sha":null,"homepage":"https://weaverse.io/demo","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Weaverse.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2023-04-24T08:13:11.000Z","updated_at":"2024-04-15T08:56:31.251Z","dependencies_parsed_at":"2024-03-25T10:26:35.413Z","dependency_job_id":"0f60f799-31aa-41f5-b34d-e3468515b1e0","html_url":"https://github.com/Weaverse/pilot","commit_stats":null,"previous_names":[],"tags_count":8,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Weaverse%2Fpilot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Weaverse%2Fpilot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Weaverse%2Fpilot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Weaverse%2Fpilot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Weaverse","download_url":"https://codeload.github.com/Weaverse/pilot/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244722706,"owners_count":20499151,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["headless-commerce","hydrogen","remix","shopify-hydrogen","shopify-storefront"],"created_at":"2025-03-21T01:36:16.354Z","updated_at":"2026-05-04T12:06:43.612Z","avatar_url":"https://github.com/Weaverse.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003ePilot - Production-ready Shopify Hydrogen Theme\u003c/h1\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n📚 [Read the docs](https://weaverse.io/docs) | 🗣 [Join our community on Slack](https://join.slack.com/t/weaversecommunity/shared_invite/zt-235bv7d80-velzJU8CpZIHWdrzFwAdXg) | 🐞 [Report a bug](https://github.com/weaverse/pilot/issues)\n\n\u003c/div\u003e\n\n![Weaverse + Hydrogen + Shopify](https://cdn.shopify.com/s/files/1/0838/0052/3057/files/weaverse-x-hydrogen-x-shopify.png?v=1755245801)\n\n_Pilot is an innovative Shopify theme, powered by Hydrogen, React Router 7, and Weaverse, designed to create lightning-fast storefronts with exceptional performance. This theme combines a collection of powerful tools and features to streamline your Shopify development experience._\n\n## Who is using Weaverse/Pilot on production?\nThese **Shopify (Plus)** brands built on top of Weaverse/Pilot:\n- [Huckleberry Roasters](https://www.huckleberryroasters.com/) - Crafting coffee in Colorado since 2011, Huckleberry Roasters delivers award-winning flavors with ethically sourced beans.\n- [Bubble Goods](https://bubblegoods.com/) - 2,000+ healthy food products shipped from small independent U.S. makers to your door.\n- [Karma and Luck](https://www.karmaandluck.com) - modern lifestyle brand rooted in timeless traditions and spiritual intention.\n- [Baltzar](https://baltzar.com/) - curated selection of menswear brands from world renowned specialists such as Frank Clegg, Albert Thurston and Astorflex.\n- [iROCKER](https://irockersup.com/) - provide life on the water to all, with gear that goes the extra mile.\n- [Roland (Brazil)](https://store.roland.com.br/) - electronic musical instruments, drums, digital pianos, synthesizers, and dance/DJ gears.\n- [Timothy London](https://timothy.london/) - British brand of premium travel goods and accessories.\n- [Vasuma Eyewear](https://vasuma.com/) - Vasuma creates eyewear for both men and women. From Stockholm, Sweden our eyewear are inspired by the best of the vintage eras of the 50s and 60s.\n- And many more...\n\n## AI Coding Agent Support\n\nPilot supports AI coding agents (Cursor, Claude Code, Windsurf, Codex, GitHub Copilot) via `AGENTS.md`, which includes inline Weaverse component patterns, schema reference, input types, loader patterns, and common pitfalls.\n\n## Links\n\n- Live store: https://pilot.weaverse.dev\n- Customizing Pilot on Weaverse Studio: https://studio.weaverse.io/demo?theme=pilot\n  ![pilot.weaverse.dev](https://cdn.shopify.com/s/files/1/0838/0052/3057/files/pilot.weavverse.dev_0b0b2f77-b79e-4524-8cf5-bc22d6ec4ba9.png?v=1744963684)\n\n## What's included\n\n- Shopify Hydrogen / Oxygen / CLI\n- Shopify Basic/Plus features support:\n  - New [Shopify Customer Account API](https://www.shopify.com/partners/blog/introducing-customer-account-api-for-headless-stores) (OAuth-based)\n  - [Combined Listings](https://shopify.dev/docs/apps/build/product-merchandising/combined-listings)\n  - [Product bundles](https://help.shopify.com/en/manual/products/bundles)\n- [React Router 7](https://reactrouter.com/) for routing/SSR/data loading\n- [Biome](https://biomejs.dev/) code linter/formatter\n- TypeScript with strict configuration\n- GraphQL code generator\n- Styled with [TailwindCSS](https://tailwindcss.com/) (v4)\n- [Radix-UI](https://www.radix-ui.com/) for accessible/reusable UI components\n- [class-variance-authority](https://cva.style/) (cva) for component variants\n- [Swiper](https://swiperjs.com/) for carousels/sliders\n- [Judge.me](https://judge.me/) reviews integration\n- [Klaviyo](https://www.klaviyo.com/) integration for email marketing\n- Full-featured setup of components and routes\n- Fully customizable inside [Weaverse Studio](https://weaverse.io)\n\n## Deployment\n\n- [Deploy to Shopify Oxygen](https://weaverse.io/docs/deployment/oxygen)\n- [Deploy to Vercel](https://wvse.cc/deploy-pilot-to-vercel)\n\n## Getting started\n\n**Requirements:**\n\n- Node.js version 20.0.0 or higher\n- `npm` package manager\n\n**Follow these steps to get started with Pilot and begin crafting your Hydrogen-driven storefront:**\n\n1. Install [Weaverse Hydrogen Customizer](https://apps.shopify.com/weaverse) from Shopify App Store.\n2. Create new Hydrogen storefront inside Weaverse.\n3. Initialize the project and start a local dev server with `@weaverse/cli` tool as instructed in the Weaverse Studio.\n   ![Create new Weaverse Shopify Hydrogen project](https://cdn.shopify.com/s/files/1/0838/0052/3057/files/new_hydrogen_project.png?v=1735008500)\n4. Open **Weaverse Studio** to start customizing and tailoring your storefront according to your preferences.\n\n## Quick Start Commands\n\n```bash\n# Install dependencies\nnpm install\n\n# Start development server on port 3456\nnpm run dev\n\n# Run code quality checks before committing\nnpm run biome:fix\nnpm run typecheck\n\n# Build for production\nnpm run build\n\n# Run E2E tests\nnpm run e2e\n```\n\n## Features overview\n\n### Fetching page data with parallel loading\n\nPilot uses parallel data loading for optimal performance. Every route loads Weaverse data alongside GraphQL queries using `Promise.all()`:\n\n```ts:app/routes/home.tsx\nimport type { LoaderFunctionArgs } from 'react-router';\n\nexport async function loader({ context }: LoaderFunctionArgs) {\n  const { storefront, weaverse } = context;\n\n  // Parallel data loading for best performance\n  const [weaverseData, { shop }] = await Promise.all([\n    weaverse.loadPage({ type: 'INDEX' }),\n    storefront.query(SHOP_QUERY),\n  ]);\n\n  return {\n    weaverseData,\n    shop,\n  };\n}\n```\n\n`weaverse` is an `WeaverseClient` instance that has been injected into the app context by Weaverse. It provides a set of methods to interact with the Weaverse API.\n\n```ts:app/.server/context.ts\nconst hydrogenContext = createHydrogenContext({\n  env,\n  request,\n  cache,\n  waitUntil,\n  session,\n  i18n: getLocaleFromRequest(request),\n  cart: { queryFragment: CART_QUERY_FRAGMENT },\n});\n\nconst weaverse = new WeaverseClient({\n  ...hydrogenContext,\n  request,\n  cache,\n  themeSchema,\n  components,\n});\n\nObject.assign(hydrogenContext, { weaverse });\nreturn hydrogenContext;\n```\n\n### Rendering page content\n\nWeaverse pages is rendered using `\u003cWeaverseContent /\u003e` component.\n\n```tsx:app/weaverse/index.tsx\nimport { WeaverseHydrogenRoot } from '@weaverse/hydrogen';\nimport { GenericError } from '~/components/generic-error';\nimport { components } from './components';\n\nexport function WeaverseContent() {\n  return (\n    \u003cWeaverseHydrogenRoot\n      components={components}\n      errorComponent={GenericError}\n    /\u003e\n  );\n}\n\n```\n\nAnd in your route:\n\n```tsx:app/routes/home.tsx\nexport default function Homepage() {\n  return \u003cWeaverseContent /\u003e;\n}\n```\n\nDead simple, right?\n\n### Global theme settings\n\nWeaverse global theme settings is loaded in the `root`'s loader with `context.weaverse.loadThemeSettings` function.\n\n```tsx:app/root.tsx\nexport async function loader(args: LoaderFunctionArgs) {\n  const deferredData = loadDeferredData(args);\n  const criticalData = await loadCriticalData(args);\n  return {\n    ...deferredData,\n    ...criticalData,\n  };\n}\n```\n\nAnd then you can use it in your components with `useThemeSettings` hook.\n\n```tsx:app/weaverse/components/logo.tsx\nimport { useThemeSettings } from '@weaverse/hydrogen';\n\nfunction Logo() {\n  let {logo} = useThemeSettings();\n\n  return (\n    \u003cdiv className=\"flex items-center\"\u003e\n      \u003cimg src={logo} alt=\"Logo\" /\u003e\n    \u003c/div\u003e\n  );\n}\n```\n\nThe `App` component is wrapped with `withWeaverse` HoC in order to SSR the theme settings.\n\n```tsx:app/root.tsx\nimport { withWeaverse } from '@weaverse/hydrogen';\n\nfunction App() {\n  return \u003cOutlet /\u003e;\n}\n\nexport default withWeaverse(App);\n```\n\n### Create a Weaverse section\n\nTo create a section, you need to create a new file in [`app/sections`](app/sections) directory and register it in [`app/weaverse/components.ts`](app/weaverse/components.ts) file.\n\n**Important:** All Weaverse sections must include `ref` as a prop and extend `HydrogenComponentProps`.\n\n```tsx:app/sections/video/index.tsx\nimport type { HydrogenComponentProps } from '@weaverse/hydrogen';\n\ninterface VideoProps extends HydrogenComponentProps {\n  ref: React.Ref\u003cHTMLElement\u003e\n  heading: string;\n  description: string;\n  videoUrl: string;\n}\n\nexport default function Video(props: VideoProps) {\n  const { ref, heading, description, videoUrl, ...rest } = props;\n  return (\n    \u003csection ref={ref} {...rest}\u003e\n      \u003cdiv className=\"mx-auto max-w-7xl px-4 py-8 lg:px-12 lg:py-16 sm:text-center\"\u003e\n        \u003ch2 className=\"mb-4 text-4xl font-extrabold tracking-tight text-gray-900\"\u003e\n          {heading}\n        \u003c/h2\u003e\n        \u003cp className=\"font-light text-gray-500 sm:text-lg md:px-20 lg:px-38 xl:px-48\"\u003e\n          {description}\n        \u003c/p\u003e\n        \u003ciframe\n          className=\"mx-auto mt-8 h-64 w-full max-w-2xl rounded-lg lg:mt-12 sm:h-96\"\n          src={videoUrl}\n          title=\"YouTube video player\"\n          allow=\"accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture\"\n          allowFullScreen\n        /\u003e\n      \u003c/div\u003e\n    \u003c/section\u003e\n  );\n}\n```\n\nExport a `schema` object from the file to define the component's schema with default data and settings to be used in the **Weaverse Studio**.\n\n```tsx:app/sections/video/index.tsx (continued)\nexport const schema = createSchema({\n  type: 'video',\n  title: 'Video',\n  settings: [\n    {\n      group: 'Video',\n      inputs: [\n        {\n          type: 'text',\n          name: 'heading',\n          label: 'Heading',\n          defaultValue: 'Learn More About Our Products',\n          placeholder: 'Learn More About Our Products',\n        },\n        {\n          type: 'textarea',\n          name: 'description',\n          label: 'Description',\n          defaultValue: `Watch these short videos to see our products in action. Learn how to use them and what makes them special. See demos of our products being used in real-life situations. The videos provide extra details and showcase the full capabilities of what we offer. If you're interested in learning more before you buy, be sure to check out these informative product videos.`,\n          placeholder: 'Video description',\n        },\n        {\n          type: 'text',\n          name: 'videoUrl',\n          label: 'Video URL',\n          defaultValue: 'https://www.youtube.com/embed/-akQyQN8rYM',\n          placeholder: 'https://www.youtube.com/embed/-akQyQN8rYM',\n        },\n      ],\n    },\n  ],\n});\n```\n\nWhat if your component needs to fetch data from Shopify API or any third-party API?\n\n**Weaverse** provide a powerful `loader` function to fetch data from _any_ API, and it's run on the **server-side** 🤯😎.\n\nJust export a `loader` function from your component:\n\n```tsx:app/sections/video/index.tsx (loader example)\nimport type { ComponentLoaderArgs } from '@weaverse/hydrogen';\n\nexport const loader = async ({ weaverse, data }: ComponentLoaderArgs) =\u003e {\n  const result = await weaverse.storefront.query\u003cSeoCollectionContentQuery\u003e(\n    HOMEPAGE_SEO_QUERY,\n    {\n      variables: { handle: data.collection.handle || 'frontpage' },\n    },\n  );\n  return result.data;\n};\n```\n\nAnd then you can use the data in your component with `Component.props.loaderData` 🤗\n\nDon't forget to register your new section in `app/weaverse/components.ts`:\n\n```typescript\nimport * as Video from \"~/sections/video\";\n\nexport const components: HydrogenComponent[] = [\n  // ... existing components\n  Video,\n];\n```\n\n### Manage content and style your pages within Weaverse Studio\n\nWeaverse provides a convenient way to customize your theme inside the **Weaverse Studio**. You can add new sections, customize existing ones, and change the theme settings.\n\n![Pilot in Weaverse Studio](https://cdn.shopify.com/s/files/1/0838/0052/3057/files/pilot-in-weaverse-studio.png?v=1755247352)\n\n### Project Structure\n\n```\napp/\n├── components/     # Reusable UI components\n├── sections/       # Weaverse sections/components\n├── routes/         # React Router routes (with locale prefix)\n├── graphql/        # GraphQL queries and fragments\n├── utils/          # Helper functions\n└── weaverse/       # Weaverse configuration\n\nKey configuration files:\n- biome.json                  # Code formatting and linting\n- codegen.ts                  # GraphQL code generation\n- react-router.config.ts      # React Router configuration\n- vite.config.ts              # Vite bundler configuration\n```\n\n### Development Tools\n\n- **Development server**: http://localhost:3456\n- **GraphiQL API browser**: http://localhost:3456/graphiql\n- **Network inspector**: http://localhost:3456/debug-network\n- **Weaverse Studio**: Access through your Shopify admin\n\n## References\n\n- [Weaverse docs](https://weaverse.io/docs)\n- [Hydrogen docs](https://shopify.dev/custom-storefronts/hydrogen)\n- [React Router](https://reactrouter.com/)\n- [Tailwind CSS v4](https://tailwindcss.com/)\n- [Radix UI](https://www.radix-ui.com/)\n- [Biome](https://biomejs.dev/)\n\n## License\n\nThis project is provided under the [MIT License](LICENSE).\n\n---\n\nLet **Weaverse** \u0026 **Pilot** empower your Shopify store with top-notch performance and unmatched customization possibilities! 🚀\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fweaverse%2Fpilot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fweaverse%2Fpilot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fweaverse%2Fpilot/lists"}