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 许可证发布。