nuxt-shopify
@nuxtjs/shopify

轻松将 Shopify 集成到您的 Nuxt 应用中。
759 次下载124 星v0.3.2
konkonamkonkonam
freb97freb97

Nuxt Shopify Logo

Nuxt Shopify 模块

Github ActionsNPM versionNPM last updateLicense

适用于 Shopify Storefront API 和 Shopify Admin API 的完全类型化 Fetch 客户端。您可以在服务器端和客户端使用它，内置支持 mock.shop，并能根据您的 GraphQL 查询自动热重载生成类型。

⚡️ 功能

  • 🔗 从 GraphQL 模式完全类型化的 Fetch 客户端
  • 🔥 当您的 GraphQL 发生变化时自动热重载类型
  • 🔐 安全的访问令牌处理
  • 🛒 支持 Storefront 和 Admin API
  • 🌐 支持服务器端和客户端
  • 🛠️ 自动 mock.shop 集成
  • 🚩 针对 Nuxt 优化的错误处理
  • 📡 用于 API 请求的服务器端代理
  • 🧩 GraphQL 片段支持
  • ⚙️ 可自定义的 GraphQL 代码生成
  • 📦 GraphQL 查询和生成类型的自动导入
  • 🏖️ 集成 GraphiQL Explorer 的沙盒
  • 🔄 用于自定义模块行为的钩子
  • 🧪 经过 Nuxt 3 和 4 测试

路线图

1.0.0 版本即将推出的功能和开发

  • 🏎️ 子请求缓存支持
  • 👤 客户账户 API 支持
  • 🔍 Shopify 分析支持
  • 🪝 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',
            },
        },
    },
})

🛠️ 用法

在客户端访问 Storefront API

有多种方式与 Shopify API 通信。最简单的方法是使用 useStorefront 可组合函数，直接在您的 Vue 组件或页面中。

要在客户端访问 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 与 Storefront API

您还可以使用 useStorefrontData 可组合函数从 Storefront 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 的实用工具。

Storefront API 示例

您可以使用 useStorefront 实用工具访问 Storefront 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 文件都会自动为 Storefront API 处理，只要它们不以 .admin.ts 或 .admin.gql 结尾。阅读更多关于 codegen 配置。

现在我们可以调用 /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>>，这使得自动补全和完整的类型检查成为可能。

Admin 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(...)
})

有关完整示例，请参阅 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 的请求现在将返回来自 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 许可证发布。