https://github.com/weaverse/pilot
Pilot - Shopify Hydrogen Theme, power by Weaverse Hydrogen Theme Customizer.
https://github.com/weaverse/pilot
headless-commerce hydrogen remix shopify-hydrogen shopify-storefront
Last synced: 3 months ago
JSON representation
Pilot - Shopify Hydrogen Theme, power by Weaverse Hydrogen Theme Customizer.
- Host: GitHub
- URL: https://github.com/weaverse/pilot
- Owner: Weaverse
- License: mit
- Created: 2023-04-24T08:13:11.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-04-12T05:42:03.000Z (over 2 years ago)
- Last Synced: 2024-04-13T13:02:18.892Z (over 2 years ago)
- Topics: headless-commerce, hydrogen, remix, shopify-hydrogen, shopify-storefront
- Language: TypeScript
- Homepage: https://weaverse.io/demo
- Size: 2.06 MB
- Stars: 60
- Watchers: 3
- Forks: 5
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
Awesome Lists containing this project
README
Pilot - Production-ready Shopify Hydrogen Theme
📚 [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)
_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._
## Who is using Weaverse/Pilot on production?
These **Shopify (Plus)** brands built on top of Weaverse/Pilot:
- [Huckleberry Roasters](https://www.huckleberryroasters.com/) - Crafting coffee in Colorado since 2011, Huckleberry Roasters delivers award-winning flavors with ethically sourced beans.
- [Bubble Goods](https://bubblegoods.com/) - 2,000+ healthy food products shipped from small independent U.S. makers to your door.
- [Karma and Luck](https://www.karmaandluck.com) - modern lifestyle brand rooted in timeless traditions and spiritual intention.
- [Baltzar](https://baltzar.com/) - curated selection of menswear brands from world renowned specialists such as Frank Clegg, Albert Thurston and Astorflex.
- [iROCKER](https://irockersup.com/) - provide life on the water to all, with gear that goes the extra mile.
- [Roland (Brazil)](https://store.roland.com.br/) - electronic musical instruments, drums, digital pianos, synthesizers, and dance/DJ gears.
- [Timothy London](https://timothy.london/) - British brand of premium travel goods and accessories.
- [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.
- And many more...
## AI Coding Agent Support
Pilot 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.
## Links
- Live store: https://pilot.weaverse.dev
- Customizing Pilot on Weaverse Studio: https://studio.weaverse.io/demo?theme=pilot
## What's included
- Shopify Hydrogen / Oxygen / CLI
- Shopify Basic/Plus features support:
- New [Shopify Customer Account API](https://www.shopify.com/partners/blog/introducing-customer-account-api-for-headless-stores) (OAuth-based)
- [Combined Listings](https://shopify.dev/docs/apps/build/product-merchandising/combined-listings)
- [Product bundles](https://help.shopify.com/en/manual/products/bundles)
- [React Router 7](https://reactrouter.com/) for routing/SSR/data loading
- [Biome](https://biomejs.dev/) code linter/formatter
- TypeScript with strict configuration
- GraphQL code generator
- Styled with [TailwindCSS](https://tailwindcss.com/) (v4)
- [Radix-UI](https://www.radix-ui.com/) for accessible/reusable UI components
- [class-variance-authority](https://cva.style/) (cva) for component variants
- [Swiper](https://swiperjs.com/) for carousels/sliders
- [Judge.me](https://judge.me/) reviews integration
- [Klaviyo](https://www.klaviyo.com/) integration for email marketing
- Full-featured setup of components and routes
- Fully customizable inside [Weaverse Studio](https://weaverse.io)
## Deployment
- [Deploy to Shopify Oxygen](https://weaverse.io/docs/deployment/oxygen)
- [Deploy to Vercel](https://wvse.cc/deploy-pilot-to-vercel)
## Getting started
**Requirements:**
- Node.js version 20.0.0 or higher
- `npm` package manager
**Follow these steps to get started with Pilot and begin crafting your Hydrogen-driven storefront:**
1. Install [Weaverse Hydrogen Customizer](https://apps.shopify.com/weaverse) from Shopify App Store.
2. Create new Hydrogen storefront inside Weaverse.
3. Initialize the project and start a local dev server with `@weaverse/cli` tool as instructed in the Weaverse Studio.
4. Open **Weaverse Studio** to start customizing and tailoring your storefront according to your preferences.
## Quick Start Commands
```bash
# Install dependencies
npm install
# Start development server on port 3456
npm run dev
# Run code quality checks before committing
npm run biome:fix
npm run typecheck
# Build for production
npm run build
# Run E2E tests
npm run e2e
```
## Features overview
### Fetching page data with parallel loading
Pilot uses parallel data loading for optimal performance. Every route loads Weaverse data alongside GraphQL queries using `Promise.all()`:
```ts:app/routes/home.tsx
import type { LoaderFunctionArgs } from 'react-router';
export async function loader({ context }: LoaderFunctionArgs) {
const { storefront, weaverse } = context;
// Parallel data loading for best performance
const [weaverseData, { shop }] = await Promise.all([
weaverse.loadPage({ type: 'INDEX' }),
storefront.query(SHOP_QUERY),
]);
return {
weaverseData,
shop,
};
}
```
`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.
```ts:app/.server/context.ts
const hydrogenContext = createHydrogenContext({
env,
request,
cache,
waitUntil,
session,
i18n: getLocaleFromRequest(request),
cart: { queryFragment: CART_QUERY_FRAGMENT },
});
const weaverse = new WeaverseClient({
...hydrogenContext,
request,
cache,
themeSchema,
components,
});
Object.assign(hydrogenContext, { weaverse });
return hydrogenContext;
```
### Rendering page content
Weaverse pages is rendered using `` component.
```tsx:app/weaverse/index.tsx
import { WeaverseHydrogenRoot } from '@weaverse/hydrogen';
import { GenericError } from '~/components/generic-error';
import { components } from './components';
export function WeaverseContent() {
return (
);
}
```
And in your route:
```tsx:app/routes/home.tsx
export default function Homepage() {
return ;
}
```
Dead simple, right?
### Global theme settings
Weaverse global theme settings is loaded in the `root`'s loader with `context.weaverse.loadThemeSettings` function.
```tsx:app/root.tsx
export async function loader(args: LoaderFunctionArgs) {
const deferredData = loadDeferredData(args);
const criticalData = await loadCriticalData(args);
return {
...deferredData,
...criticalData,
};
}
```
And then you can use it in your components with `useThemeSettings` hook.
```tsx:app/weaverse/components/logo.tsx
import { useThemeSettings } from '@weaverse/hydrogen';
function Logo() {
let {logo} = useThemeSettings();
return (
);
}
```
The `App` component is wrapped with `withWeaverse` HoC in order to SSR the theme settings.
```tsx:app/root.tsx
import { withWeaverse } from '@weaverse/hydrogen';
function App() {
return ;
}
export default withWeaverse(App);
```
### Create a Weaverse section
To 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.
**Important:** All Weaverse sections must include `ref` as a prop and extend `HydrogenComponentProps`.
```tsx:app/sections/video/index.tsx
import type { HydrogenComponentProps } from '@weaverse/hydrogen';
interface VideoProps extends HydrogenComponentProps {
ref: React.Ref
heading: string;
description: string;
videoUrl: string;
}
export default function Video(props: VideoProps) {
const { ref, heading, description, videoUrl, ...rest } = props;
return (
{heading}
{description}
);
}
```
Export a `schema` object from the file to define the component's schema with default data and settings to be used in the **Weaverse Studio**.
```tsx:app/sections/video/index.tsx (continued)
export const schema = createSchema({
type: 'video',
title: 'Video',
settings: [
{
group: 'Video',
inputs: [
{
type: 'text',
name: 'heading',
label: 'Heading',
defaultValue: 'Learn More About Our Products',
placeholder: 'Learn More About Our Products',
},
{
type: 'textarea',
name: 'description',
label: 'Description',
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.`,
placeholder: 'Video description',
},
{
type: 'text',
name: 'videoUrl',
label: 'Video URL',
defaultValue: 'https://www.youtube.com/embed/-akQyQN8rYM',
placeholder: 'https://www.youtube.com/embed/-akQyQN8rYM',
},
],
},
],
});
```
What if your component needs to fetch data from Shopify API or any third-party API?
**Weaverse** provide a powerful `loader` function to fetch data from _any_ API, and it's run on the **server-side** 🤯😎.
Just export a `loader` function from your component:
```tsx:app/sections/video/index.tsx (loader example)
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;
};
```
And then you can use the data in your component with `Component.props.loaderData` 🤗
Don't forget to register your new section in `app/weaverse/components.ts`:
```typescript
import * as Video from "~/sections/video";
export const components: HydrogenComponent[] = [
// ... existing components
Video,
];
```
### Manage content and style your pages within Weaverse Studio
Weaverse 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.
### Project Structure
```
app/
├── components/ # Reusable UI components
├── sections/ # Weaverse sections/components
├── routes/ # React Router routes (with locale prefix)
├── graphql/ # GraphQL queries and fragments
├── utils/ # Helper functions
└── weaverse/ # Weaverse configuration
Key configuration files:
- biome.json # Code formatting and linting
- codegen.ts # GraphQL code generation
- react-router.config.ts # React Router configuration
- vite.config.ts # Vite bundler configuration
```
### Development Tools
- **Development server**: http://localhost:3456
- **GraphiQL API browser**: http://localhost:3456/graphiql
- **Network inspector**: http://localhost:3456/debug-network
- **Weaverse Studio**: Access through your Shopify admin
## References
- [Weaverse docs](https://weaverse.io/docs)
- [Hydrogen docs](https://shopify.dev/custom-storefronts/hydrogen)
- [React Router](https://reactrouter.com/)
- [Tailwind CSS v4](https://tailwindcss.com/)
- [Radix UI](https://www.radix-ui.com/)
- [Biome](https://biomejs.dev/)
## License
This project is provided under the [MIT License](LICENSE).
---
Let **Weaverse** & **Pilot** empower your Shopify store with top-notch performance and unmatched customization possibilities! 🚀