nuxt-shopify
@nuxtjs/shopify

輕鬆將 Shopify 整合到您的 Nuxt 應用程式中。
653 次下載123 顆星v0.2.0
konkonamkonkonam
freb97freb97

Nuxt Shopify Logo

Nuxt Shopify 模組

Github ActionsNPM versionNPM downloadsNPM last updateLicense

適用於 Shopify 店面 API 和 Shopify 管理 API 的全型別化 fetch 客戶端。您可以在伺服器端和客戶端使用它，內建支援 mock.shop，並能根據您的 GraphQL 查詢自動熱過載型別生成。

⚡️ 功能

  • 🔗 從 GraphQL 模式生成完全型別化的 fetch 客戶端
  • 🔥 當您的 GraphQL 發生變化時自動熱過載型別
  • 🔐 安全訪問令牌處理
  • 🛒 支援店面和管理 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
或者使用手動安裝
  1. 透過 npm 安裝模組
    npm install @nuxtjs/shopify
  2. 將模組新增到您的 nuxt.config.ts
    export default defineNuxtConfig({
    modules: [
        '@nuxtjs/shopify',
    ],
})

將您的 Shopify 配置新增到 nuxt.config.ts

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

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

🛠️ 用法

在客戶端訪問店面 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 商店獲取前三個產品，並在 <pre> 標籤中顯示它們。

data 變數將被型別化為 FetchProductsQuery，這是由模組自動生成的，以實現自動補全和全面的型別檢查。

您可以在程式碼中的任何地方使用這個生成的 FetchProductsQuery 型別，以確保在元件中處理查詢響應時的型別安全。

結合 useAsyncData 使用店面 API

您還可以使用 useStorefrontData 可組合函式從店面 API 獲取資料，同時利用 Nuxt 內建的非同步資料獲取功能。

<!-- ~/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 的實用工具。

店面 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 指令，這是因為在標準模組配置中，所有 .ts 和 .gql 檔案都會自動為店面 API 進行處理，只要它們不以 .admin.ts 或 .admin.gql 結尾。閱讀更多關於 程式碼生成配置 的資訊。

現在我們可以呼叫 /api/products API 來獲取前三個產品

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

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

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

data 變數將被型別化為 Ref<ClientResponse<FetchProductsQuery>>，這使得自動補全和全面的型別檢查成為可能。

管理員 API 示例

以 .admin.ts 或 .admin.gql 結尾的檔案將自動為管理 API 處理。我們可以在 Nitro 事件處理程式中使用 useAdmin 實用工具來訪問管理 API

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

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

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

有關完整示例，請參閱 管理員 API 示例。

模擬店面 API

要模擬店面 API，您可以在模組配置中使用 mock 選項

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

        clients: {
            storefront: {
                mock: true,

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

現在，所有對店面 API 的請求都將從 mock.shop 返回資料，而不是實際呼叫 Shopify API。

代理客戶端請求

預設情況下，所有從客戶端發出的請求都會透過 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)
    })
})

在我們的鉤子文件中閱讀更多關於所有可用鉤子的資訊。

👥 維護者

🤝 貢獻

  1. 克隆此倉庫
  2. 建立一個 .env 檔案（參見 .env.example）
  3. 使用以下命令安裝依賴項
    bun install
  4. 執行 bun run prepare:dev 生成型別存根。
  5. 使用以下命令啟動預設的 playground
    bun run dev

📜 許可證

根據 MIT 許可證釋出。