@nuxtjs/shopify

ShopifyをNuxtアプリに簡単に統合できます。

653ダウンロード•123スター•v0.2.0

Nuxt Shopifyモジュール

Shopify Storefront APIおよびShopify Admin API用の完全に型付けされたフェッチクライアントです。サーバー側とクライアント側の両方で使用でき、mock.shopの組み込みサポートと、GraphQLクエリからの自動ホットリロード型生成機能が含まれています。

⚡️ 特徴

🔗 GraphQLスキーマからの完全に型付けされたフェッチクライアント
🔥 GraphQLの変更時に型を自動的にホットリロード
🔐 安全なアクセストークン処理
🛒 ストアフロントAPIと管理APIのサポート
🌐 サーバー＆クライアント側のサポート
🛠️ 自動mock.shop連携
🚩 Nuxtに最適化されたエラーハンドリング
📡 APIリクエスト用のサーバーサイドプロキシ
🧩 GraphQLフラグメントのサポート
⚙️ カスタマイズ可能なGraphQLコード生成
📦 GraphQLクエリと生成された型の自動インポート
🏖️ GraphiQL Explorerと統合されたサンドボックス
🔄 モジュールの動作をカスタマイズするためのフック
🧪 Nuxt 3 & 4でテスト済み

ロードマップ

バージョン1.0.0リリースに向けての今後の機能と開発

🏎️ サブリクエストキャッシュのサポート
👤 顧客アカウントAPIのサポート
🔍 Shopify Analyticsのサポート
🪝 Webhook購読のサポート
🛍️ Nuxt UI & Nuxt Contentを使用したストアテンプレート

📦 セットアップ

プロジェクトにモジュールをインストールするには、以下のコマンドを実行してください。

npx nuxt@latest module add nuxt-shopify

または、手動インストールを使用してください。

npm経由でモジュールをインストールします。
```
npm install @nuxtjs/shopify
```

nuxt.config.ts にモジュールを追加します

export default defineNuxtConfig({
    modules: [
        '@nuxtjs/shopify',
    ],
})

nuxt.config.tsにShopifyの設定を追加します。

export default defineNuxtConfig({
    shopify: {
        name: 'quickstart-abcd1234',
        clients: {
            storefront: {
                apiVersion: '2025-07',
                publicAccessToken: 'YOUR_ACCESS_TOKEN',
            },

            admin: {
                apiVersion: '2025-07',
                accessToken: 'YOUR_ACCESS_TOKEN',
            },
        },
    },
})

🛠️ 使用方法

クライアント側でのStorefront APIへのアクセス

Shopify APIと通信する方法は複数あります。最も簡単な方法は、Vueコンポーネントまたはページ内で直接useStorefrontコンポーザブルを使用することです。

クライアント側でuseStorefrontコンポーザブルにアクセスするには、公開アクセストークンを追加してください。モジュール設定のclients > storefront > publicAccessTokenに追加できます。

<!-- ~/pages/your-page.vue -->

<script setup lang="ts">
const storefront = useStorefront()

const { data } = await storefront.request(`#graphql
    query FetchProducts($first: Int) {
        products(first: $first) {
            nodes {
                id
                title
                description
            }
        }
    }
`, {
    variables: {
        first: 3,
    },
})
</script>

<template>
    <pre>{{ data?.products }}</pre>
</template>

これにより、Shopifyストアから最初の3つの製品がフェッチされ、<pre>タグ内に表示されます。

data変数はFetchProductsQueryとして型付けされます。これは、オートコンプリートと完全な型チェックを可能にするためにモジュールによって自動生成されます。

この生成されたFetchProductsQuery型は、コンポーネント内でクエリ応答を扱う際に型安全性を確保するために、コードのどこでも使用できます。

useAsyncDataでStorefront APIを使用する

useStorefrontDataコンポーザブルを使用して、Nuxtに組み込まれた非同期データフェッチ機能を活用しながらStorefront APIからデータをフェッチすることもできます。

<!-- ~/pages/your-page.vue -->

<script setup lang="ts">
const { data: products, error } = await useStorefrontData('products', `#graphql
    query FetchProducts($first: Int) {
        products(first: $first) {
            nodes {
                id
                title
                description
            }
        }
    }
`, {
    variables: {
        first: 3,
    },

    // Use features from useAsyncData, e.g. transform, pick, etc.
    transform: (data) => flattenConnection(data.products),
})
</script>

<template>
    <pre>{{ products }}</pre>
</template>

useStorefrontDataは、確実に文字列化できるように、応答からdataプロパティを自動的に抽出することに注意してください。errors: { throw: false }の設定と併用する場合、useStorefrontDataコンポーザブルによって返されるerrorオブジェクトを使用する代わりに、応答内でエラーを手動で確認する必要があります。

Nitroエンドポイント経由でのAPIアクセス

モジュールは、Nitroエンドポイント経由で各APIにアクセスするためのユーティリティを公開しています。

Storefront APIの例

useStorefrontユーティリティを使用して、ストアフロントAPIにアクセスできます。

// ~/server/api/products.ts

export default defineEventHandler(async () => {
    const storefront = useStorefront()

    return await storefront.request(`#graphql
        query FetchProducts($first: Int) {
            products(first: $first) {
                nodes {
                    id
                    title
                    description
                }
            }
        }
    `, {
        variables: {
            first: 3,
        },
    })
})

イベントハンドラー内でgraphqlディレクティブを使用できることに注目してください。これは、標準モジュール設定では、.admin.tsまたは.admin.gqlで終わらない限り、すべての.tsおよび.gqlファイルがストアフロントAPI向けに自動的に処理されるためです。codegen設定の詳細については、こちらをご覧ください。

これで、/api/productsでAPIを呼び出して最初の3つの製品を取得できます。

<!-- ~/pages/your-page.vue -->

<script setup lang="ts">
const { data } = await useFetch('/api/products')
</script>

<template>
    <pre>{{ data }}</pre>
</template>

data変数はRef<ClientResponse<FetchProductsQuery>>として型付けされ、オートコンプリートと完全な型チェックが可能になります。

Admin APIの例

.admin.tsまたは.admin.gqlで終わるファイルは、自動的にAdmin API用に処理されます。NitroイベントハンドラーでuseAdminユーティリティを使用してAdmin APIにアクセスできます。

// ~/server/api/your-admin-api-handler.ts

export default defineEventHandler(async () => {
    const admin = useAdmin()

    return await admin.request(...)
})

完全な例については、Admin APIの例を参照してください。

Storefront APIをモックする

Storefront APIをモックするには、モジュール設定でmockオプションを使用できます。

export default defineNuxtConfig({
    shopify: {
        name: 'my-mocked-shopify-store',

        clients: {
            storefront: {
                mock: true,

                apiVersion: '2025-07',
            },
        },
    },
})

Storefront APIへのすべてのリクエストは、実際のShopify APIにアクセスする代わりに、mock.shopからデータを返すようになります。

クライアントリクエストのプロキシ

クライアント側から送信されるすべてのリクエストは、デフォルトでNitroサーバーを介してプロキシされます。プロキシを無効にするには、モジュール設定でproxyオプションを設定します。プロキシはSSRモードでのみ利用可能です。

export default defineNuxtConfig({
    shopify: {
        clients: {
            storefront: {
                proxy: true,
            },
        },
    },
})

型生成

インストールすると、モジュールはGraphQL型を自動的に生成し、次の場所に保存します。

.nuxt/types — 型定義
.nuxt/schema — GraphQLスキーマファイル

IDEサポートを有効にするには、GraphQL設定ファイルを追加します。

# ~/graphql.config.yml

schema:
  - ./.nuxt/schema/storefront.schema.json
  - ./.nuxt/schema/admin.schema.json

GraphQLフラグメントの処理

GraphQLクエリで再利用可能なフラグメントを定義して、重複を避け、クエリの保守性を高めることができます。このモジュールは、フラグメントの使用をすぐにサポートしています。

フラグメントを定義して使用する例を以下に示します。

#graphql
fragment ProductFields on Product {
    id
    title
    description
}

query FetchProducts($first: Int) {
    products(first: $first) {
        nodes {
            ...ProductFields
        }
    }
}

このクエリを.gql、.ts、または.vueファイルに配置し、リクエストで使用できます。モジュールはフラグメントをインポートし、GraphQL操作内で直接使用できるようにします。

~/graphqlディレクトリに配置されたファイルは、モジュールによって自動的にインポートされるため、そこにフラグメントを整理することをお勧めします。

エラー処理

デフォルトでは、ストアフロントクライアントまたは管理クライアントでエラーが発生した場合、モジュールは応答でエラーオブジェクトを返すのではなく、エラーをスローします。これは、Nuxtがエラー処理を引き継ぐことができるようにするためです。

モジュール設定でerrors.throwオプションを設定することで、この動作をカスタマイズできます。

export default defineNuxtConfig({
    shopify: {
        errors: {
            throw: false,
        },
    },
})

これにより、モジュールはエラーをスローせず、代わりにエラー応答を返します。

モジュールはエラーを処理するためのフックも提供します。

// ~/server/plugins/your-plugin.ts
export default defineNitroPlugin((nitroApp) => {
    nitroApp.hooks.hook('storefront:client:errors', ({ errors }) => {
        // Do something with the errors
        console.log('Storefront client errors:', errors)
    })
})

利用可能なすべてのフックの詳細については、フックのドキュメントを参照してください。

👥 メンテナー

Frederik Bußmann (@freb97)
Zoltan Lukacs (@konkonam)

🤝 貢献

このリポジトリをクローンする
.envファイルを作成します（.env.exampleを参照）。
次のコマンドを使用して依存関係をインストールします。
```
bun install
```
型スタブを生成するためにbun run prepare:devを実行します。
次のコマンドでデフォルトのプレイグラウンドを開始します。
```
bun run dev
```

📜 ライセンス

MITライセンスで公開されています。