weaverse-hydrogen

Weaverse Hydrogen — エージェントスキル

Weaverse のビジュアルページビルダーを使って、Shopify Hydrogen のストアフロントを構築します。 ドキュメント：https://docs.weaverse.io | GitHub：https://github.com/Weaverse

最新のドキュメント

このスキルのフォルダーから、以下を実行してください。ヘルパーは隣接する shopify-hydrogen スキルに含まれているため、パック全体がインストールされていれば ../shopify-hydrogen/scripts/ が存在します。

このスキル単体でインストールした場合、そのフォルダーは存在せず、以下のコマンドは MODULE_NOT_FOUND で失敗します。ヘルパーを一度追加してください。

npx skills add Weaverse/shopify-hydrogen-skills --skill shopify-hydrogen

インストールしない場合でも、このスキルの references/ ファイルをオフラインの代替資料として利用できます。

最新の Weaverse ドキュメントを確認するには、以下のスクリプトを使用してください。

• node ../shopify-hydrogen/scripts/search_weaverse_docs.mjs "<query>" — Weaverse のドキュメントを検索
• node ../shopify-hydrogen/scripts/get_weaverse_page.mjs "<page-path>" — 特定のページを取得（検索結果のパスを使用）
• Weaverse のドキュメント：https://docs.weaverse.io

例：

node ../shopify-hydrogen/scripts/search_weaverse_docs.mjs "component schema"
node ../shopify-hydrogen/scripts/search_weaverse_docs.mjs "data fetching"
node ../shopify-hydrogen/scripts/get_weaverse_page.mjs "development-guide/component-schema"
node ../shopify-hydrogen/scripts/get_weaverse_page.mjs "api-reference/weaverse-client"

以下のリファレンスファイルはオフラインで参照できますが、最新の変更が反映されていない場合があります。

---

Weaverse とは？

Weaverse は Shopify Hydrogen 向けのビジュアルページビルダーです。マーチャントはドラッグ＆ドロップ式の Studio でストアフロントをカスタマイズでき、開発者はエディター UI を定義するスキーマを備えた、型安全な React コンポーネントを構築できます。

技術スタック： React 19 · React Router v7 · Shopify Hydrogen · TypeScript · Tailwind CSS · Vite

---

1. プロジェクト構成

app/
├── components/        # Reusable UI components
├── graphql/           # GraphQL queries & fragments
├── hooks/             # Custom React hooks
├── routes/            # React Router v7 route files
├── sections/          # Weaverse section components ← YOUR WORK GOES HERE
├── styles/            # Global styles + Tailwind
├── weaverse/
│   ├── components.ts  # Component registry
│   ├── schema.server.ts  # Theme schema (global settings)
│   └── csp.ts         # Content Security Policy for Weaverse
├── entry.client.tsx
├── entry.server.tsx
└── root.tsx           # Wrapped with withWeaverse(App)
server.ts              # WeaverseClient initialization
vite.config.ts
react-router.config.ts
tailwind.config.js
.env

---

2. コンポーネントの構成

すべての Weaverse コンポーネントは、1 つのファイル（またはディレクトリ）から最大 3 つのエクスポートを持ちます。

// app/sections/my-section/index.tsx

// 1. Default export — React component
function MySection(props: MySectionProps) { ... }
export default MySection;

// 2. Schema export — editor configuration
export let schema = createSchema({ ... });

// 3. Loader export (optional) — server-side data fetching
export let loader = async (args: ComponentLoaderArgs<DataType>) => { ... };

最小限の例

import { createSchema } from '@weaverse/hydrogen';
import type { HydrogenComponentProps } from '@weaverse/hydrogen';

interface BannerProps extends HydrogenComponentProps {
  heading: string;
  description: string;
}

function Banner({ heading, description, children, ...rest }: BannerProps) {
  return (
    <section {...rest} className="py-16 px-4 text-center">
      <h2 className="text-3xl font-bold">{heading}</h2>
      <p className="mt-4 text-lg text-gray-600">{description}</p>
      {children}
    </section>
  );
}

export default Banner;

export let schema = createSchema({
  type: 'banner',
  title: 'Banner',
  settings: [
    {
      group: 'Content',
      inputs: [
        { type: 'text', name: 'heading', label: 'Heading', defaultValue: 'Hello World' },
        { type: 'textarea', name: 'description', label: 'Description', defaultValue: 'Welcome to our store.' },
      ],
    },
  ],
  presets: {
    heading: 'Hello World',
    description: 'Welcome to our store.',
  },
});

主なルール

• ルート要素に {...rest} を展開してください。Weaverse Studio との連携に必要です。
• 子コンポーネントを受け入れるコンポーネント（childTypes）では、{children} をレンダリングしてください。
• React 19 では forwardRef は任意です。React 18 を使用する場合は、forwardRef でラップし、ルート要素に ref を設定してください。
• type は全コンポーネントで一意にする必要があります。 kebab-case を使用してください（例：hero-banner）。

---

3. コンポーネントの登録

コンポーネントは app/weaverse/components.ts に登録する必要があります。

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

// MUST use namespace imports (import * as X), NOT default imports
import * as HeroBanner from '~/sections/hero-banner';
import * as FeaturedCollection from '~/sections/featured-collection';
import * as ProductCard from '~/sections/product-card';

export let components: HydrogenComponent[] = [
  HeroBanner,
  FeaturedCollection,
  ProductCard,
];

よくある間違い： import HeroBanner from ... を使用すること。これは機能しません。必ず import * as HeroBanner from ... を使用してください。

---

4. createSchema() を使ったスキーマ

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

export let schema = createSchema({
  type: 'my-component',          // Unique kebab-case identifier
  title: 'My Component',         // Display name in Studio
  limit: 1,                      // Max instances per page (optional)
  enabled: ({ page, group }) =>  // Dynamic insertion availability (optional)
    ['PRODUCT', 'COLLECTION'].includes(page.type) && group === 'body',
  settings: [                    // Editor UI groups
    {
      group: 'Content',
      inputs: [
        { type: 'text', name: 'heading', label: 'Heading', defaultValue: 'Title' },
        { type: 'richtext', name: 'body', label: 'Body' },
        { type: 'image', name: 'image', label: 'Image' },
        {
          type: 'select', name: 'layout', label: 'Layout',
          configs: {
            options: [
              { value: 'grid', label: 'Grid' },
              { value: 'list', label: 'List' },
            ],
          },
          defaultValue: 'grid',
        },
      ],
    },
  ],
  childTypes: ['product-card', 'button'],  // Allowed child component types
  presets: {                     // Defaults when component is added to page
    heading: 'Title',
    layout: 'grid',
    children: [
      { type: 'product-card' },
      { type: 'product-card' },
    ],
  },
});

inspector は非推奨です。 必ず settings を使用してください。

enabledOn は非推奨です。 ページ／グループの判定は enabled に移してください。このコールバックは同期的に実行され、ストアフロントのプレビューで { page: { id, type, handle, locale }, group } を受け取ります。エラー、Promise、またはブール値以外の結果が返された場合、新規追加時にはコンポーネントが非表示になりますが、既存のインスタンスには影響しません。現在、Studio は body グループを評価します。

enabled で使用できるページタイプ： INDEX、PRODUCT、ALL_PRODUCTS、COLLECTION、COLLECTION_LIST、PAGE、BLOG、ARTICLE、CUSTOM

5. 入力タイプ（クイックリファレンス）

タイプ	戻り値	用途
text	string	1行のテキスト
textarea	string	複数行のテキスト
richtext	string (HTML)	書式設定可能なリッチテキスト
url	string	URL／リンク
image	WeaverseImage object	Shopify Files から画像を選択
video	WeaverseVideo object	Shopify Files から動画を選択
color	string (#hex)	カラーピッカー
range	number	スライダー（configs: { min, max, step } が必要です）
switch	boolean	オン／オフの切り替え
select	string	ドロップダウン（configs: { options } が必要です）
toggle-group	string	ボタングループ（configs: { options } が必要です）
heading	—	設定パネルのセクション見出し（データなし）
datepicker	number (timestamp)	日付／時刻ピッカー
product	Shopify product	商品ピッカー
collection	Shopify collection	コレクションピッカー
blog	Shopify blog	ブログピッカー
article	Shopify article	記事ピッカー
metaobject	Shopify metaobject	Metaobject ピッカー
product-list	Shopify products[]	複数商品のピッカー
collection-list	Shopify collections[]	複数コレクションのピッカー

→ 詳細：references/04-input-settings.md

---

6. データ取得

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

type MyData = { collectionHandle: string };

export let loader = async ({ weaverse, data }: ComponentLoaderArgs<MyData>) => {
  let { storefront } = weaverse;
  return await storefront.query(COLLECTION_QUERY, {
    variables: { handle: data.collectionHandle },
  });
};

// Derive props type from loader return
type Props = HydrogenComponentProps<Awaited<ReturnType<typeof loader>>> & MyData;

function MyComponent({ loaderData, ...rest }: Props) {
  let collection = loaderData?.collection;
  return <section {...rest}>{collection?.title}</section>;
}
export default MyComponent;

主なパターン：

• weaverse.storefront.query() — Shopify Storefront API
• weaverse.fetchWithCache(url, options) — キャッシュを利用した外部 API
• Promise.all([...]) — 並列取得
• ローダーに影響するスキーマ入力に shouldRevalidate: true を設定

→ 詳細：references/05-data-fetching.md

---

7. スタイリングとテーマ設定

主なスタイリング方法には Tailwind CSS を使用します。

グローバルテーマ設定は app/weaverse/schema.server.ts で定義し、CSS 変数を通じて適用します：

// app/components/GlobalStyle.tsx
import { useThemeSettings } from '@weaverse/hydrogen';

export function GlobalStyle() {
  let settings = useThemeSettings();
  if (!settings) return null;
  return (
    <style dangerouslySetInnerHTML={{ __html: `
      :root {
        --color-primary: ${settings.colorPrimary};
        --body-base-size: ${settings.bodyBaseSize}px;
        --heading-base-size: ${settings.headingBaseSize}px;
      }
    `}} />
  );
}

コンポーネントのバリアントには CVA (Class Variance Authority) を使用します：

import { cva } from 'class-variance-authority';
let buttonVariants = cva('inline-flex items-center rounded font-medium', {
  variants: {
    variant: { primary: 'bg-blue-600 text-white', secondary: 'bg-gray-200' },
    size: { sm: 'h-8 px-3 text-sm', md: 'h-10 px-4', lg: 'h-12 px-6' },
  },
  defaultVariants: { variant: 'primary', size: 'md' },
});

→ 詳細：references/06-styling-theming.md

---

8. Weaverse API（主なフックとユーティリティ）

API	目的
createSchema()	Zod によるバリデーションを使用してコンポーネントスキーマを定義
WeaverseClient	サーバーサイドクライアント（server.ts で初期化）
weaverse.loadPage({ type, handle })	ルートローダーでページデータを読み込む
weaverse.loadThemeSettings()	グローバルテーマ設定を読み込む
weaverse.fetchWithCache(url)	外部 API のデータをキャッシュして取得
withWeaverse(App)	root.tsx でルート App をラップする HOC
useWeaverse()	グローバルな Weaverse インスタンスにアクセス
useThemeSettings()	グローバルテーマ設定にアクセス
useItemInstance()	特定のコンポーネントインスタンスにアクセス
useParentInstance()	親コンポーネントインスタンスにアクセス
useChildInstances()	子コンポーネントインスタンスにアクセス

→ 詳細：references/10-weaverse-api.md

---

9. サーバーのセットアップ（server.ts）

import { WeaverseClient } from '@weaverse/hydrogen';
import { components } from '~/weaverse/components';
import { themeSchema } from '~/weaverse/schema.server';

export async function createAppLoadContext(request, env, executionContext) {
  let hydrogenContext = createHydrogenContext({ env, request, cache, waitUntil, session, /* ... */ });
  return {
    ...hydrogenContext,
    weaverse: new WeaverseClient({
      ...hydrogenContext,
      request,
      cache,
      themeSchema,
      components,
    }),
  };
}

---

10. ルートとの統合

// app/routes/($locale)._index.tsx
import { WeaverseHydrogenRoot } from '@weaverse/hydrogen';

export async function loader({ context }: LoaderFunctionArgs) {
  let weaverseData = await context.weaverse.loadPage({ type: 'INDEX' });
  return { weaverseData };
}

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

商品ページの場合：

export async function loader({ context, params }: LoaderFunctionArgs) {
  let weaverseData = await context.weaverse.loadPage({
    type: 'PRODUCT',
    handle: params.productHandle,
  });
  return { weaverseData, /* other data */ };
}

---

リファレンス一覧

特定のトピックの詳細については、以下のリファレンスファイルをご覧ください。

#	ファイル	トピック
01	references/01-project-structure.md	プロジェクト構造とファイルの構成
02	references/02-creating-components.md	コンポーネントの作成と登録
03	references/03-component-schema.md	createSchema()、設定、childTypes、プリセット、enabled
04	references/04-input-settings.md	すべての入力タイプと設定
05	references/05-data-fetching.md	ローダー、Storefront API、キャッシュ
06	references/06-styling-theming.md	Tailwind、テーマ設定、CVA、CSS 変数
07	references/07-react-router-7.md	React Router v7 の規約
08	references/08-hydrogen-fundamentals.md	Hydrogen フレームワークの基本
09	references/09-deployment.md	Oxygen、Docker、環境変数
10	references/10-weaverse-api.md	すべてのフックと WeaverseClient API
11	references/11-advanced-features.md	ローカライズ、データコネクター、CSP
12	references/12-pilot-theme.md	Pilot テーマのパターンと規約
13	references/13-migration-v5.md	Remix から React Router v7 への移行
14	references/14-sdk-caching-and-diagnostics.md	SDK 5.15.x のキャッシュ、Builder 診断ヘッダー、ネストされた複数インスタンスのページ、クライアントのアップグレード

例

ファイル	内容
examples/hero-banner.tsx	スキーマ、設定グループ、childTypes、プリセットを含む完全なセクション
examples/featured-collection.tsx	ローダーと Storefront API クエリを含むセクション
examples/product-card.tsx	子コンポーネントの例
examples/components-registry.ts	登録パターン