{"id":35269158,"url":"https://github.com/liaoyio/shopify-next-app","last_synced_at":"2026-05-04T01:36:24.525Z","repository":{"id":330740087,"uuid":"1123740232","full_name":"liaoyio/shopify-next-app","owner":"liaoyio","description":"基于 Next.js  App Router 构建的的 Shopify 应用模板。","archived":false,"fork":false,"pushed_at":"2025-12-27T16:40:15.000Z","size":518,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-04T01:36:11.442Z","etag":null,"topics":["app-router-nextjs","shopify-app","shopify-polaris","tailwindcss","tanstack-react-query"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/liaoyio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-27T14:17:01.000Z","updated_at":"2025-12-27T16:40:19.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/liaoyio/shopify-next-app","commit_stats":null,"previous_names":["liaoyio/shopify-next-app"],"tags_count":0,"template":true,"template_full_name":null,"purl":"pkg:github/liaoyio/shopify-next-app","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liaoyio%2Fshopify-next-app","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liaoyio%2Fshopify-next-app/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liaoyio%2Fshopify-next-app/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liaoyio%2Fshopify-next-app/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/liaoyio","download_url":"https://codeload.github.com/liaoyio/shopify-next-app/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liaoyio%2Fshopify-next-app/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32591603,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-03T22:12:39.696Z","status":"ssl_error","status_checked_at":"2026-05-03T22:09:10.534Z","response_time":103,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["app-router-nextjs","shopify-app","shopify-polaris","tailwindcss","tanstack-react-query"],"created_at":"2025-12-30T11:50:53.062Z","updated_at":"2026-05-04T01:36:24.520Z","avatar_url":"https://github.com/liaoyio.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Shopify 应用模板 - Next.js App Router\n\n这是一个用于使用 Next.js 与 TypeScript 构建\n[Shopify 应用](https://shopify.dev/apps/getting-started)的模板项目。它包含了用\nNext.js 的 App Router 与 Server Components 搭建 Shopify 应用所需的基础能力。\n\n## 功能特性\n\n- **Next.js**：使用最新的 App Router 与 Server Components。\n- **Prisma（可选）**：用于管理数据库连接与迁移。\n- **TanStack Query**：用于与 Shopify GraphQL API 交互。\n- **App Bridge v4**：用于在前端对 API 请求进行鉴权。\n- **Shopify API library**：用于在 serverless 后端管理 OAuth。\n- **Polaris React**：用于构建高质量、风格一致的商家端界面体验。\n- **Tailwind CSS**：用于快速、灵活的样式与设计。\n- **Docker（可选）**：用于本地开发时快速启动 Postgres 数据库。\n- **Graphql-Codegen**：用于为 GraphQL 查询与 mutation 生成类型。\n\n### 安装模板\n\n你可以使用你偏好的包管理器来安装该模板：\n\n使用 pnpm（推荐）：\n\n```shell\npnpx @shopify/create-app@latest --template https://github.com/liaoyio/shopify-next-app.git\n```\n\n该命令会克隆模板并安装所需依赖。\n\n## Next.js 与 Shopify Embedded Apps\n\n本模板的目标是让你可以快速、轻松地启动一个基于 Next.js App Router 平台的\nShopify Embedded App。\n\n模板使用了 App Bridge v4 的一些特性来简化开发，例如鉴权与会话管理。\n\n### Providers\n\n- 在 `layout.tsx` 中，我们设置了一些应用运行所需的 Provider。\n  - **ApolloProvider（可选）**：为 GraphQL 查询与 mutation 配置 Apollo 上下文。\n    请求通过 Next.js 的 `/api/graphql` 路由转发，并由 Shopify API library 处理。\n  - **SessionProvider（可选）**：确保用户始终有一个有效 session，并且应用被正确安装。\n    当需要时，它会把用户重定向到鉴权流程。\n\n### App Bridge\n\n我们使用 direct api mode 与新的安装流程（install flow），让应用安装可以自动完成。\n\n```toml\n[access.admin]\ndirect_api_mode = \"offline\"\nembedded_app_direct_api_access = true\n\n[access_scopes]\n# 了解更多：https://shopify.dev/docs/apps/tools/cli/configuration#access_scopes\nscopes = \"\"\nuse_legacy_install_flow = false\n```\n\n### Token 交换（Token exchange）\n\n该应用模板默认使用 token exchange。用户在首次页面加载时获取 ID Token，并将其发送到服务端存储。\n这一步通过一个 server action 完成。\n\n同时，所有 server action 都应携带 session token；服务端在需要时会对 token 进行校验与交换（exchange）。\n\n### 环境变量\n\n为了运行应用，你需要配置一些环境变量。本仓库的 Next.js 应用位于 `web/` 目录，因此通常使用 `web/.env`。\n\n在 `web/.env` 中加入以下内容：\n\n```bash\nDATABASE_URL= # 数据库连接串 - Prisma 用于连接数据库\nDIRECT_DATABASE_URL= # 直连数据库连接串 - Prisma 迁移时使用\nPOSTGRES_PASSWORD= # 可选：本地用 docker 启动 postgres 时使用的数据库密码\n```\n\n## 技术栈\n\n该模板组合了多个第三方开源工具：\n\n- [Next.js](https://nextjs.org/) 构建 [React](https://reactjs.org/) 前端。\n\n同时配合以下 Shopify 工具来简化应用开发：\n\n- [Shopify API library](https://github.com/Shopify/shopify-api-js?tab=readme-ov-file)\n  用于在 serverless 后端管理 OAuth，让用户可以安装应用并授予 scope 权限。\n- [App Bridge React](https://shopify.dev/apps/tools/app-bridge/getting-started/using-react)\n  为前端请求添加鉴权，并在 App 的 iFrame 之外渲染组件。\n- [Apollo](https://www.apollographql.com/)：用于与 Shopify GraphQL API 交互（可选）。\n- [Prisma](https://www.prisma.io/)：用于管理数据库连接与迁移（可选）。\n  该模板对数据库类型不做绑定，你可以使用任意你想要的数据库。\n\n## 快速开始\n\n\n\u003cdetails\u003e\n  \u003csummary\u003eMacOS 安装 PostgreSQL\u003c/summary\u003e\n\n1. 安装 postgresql\n\n```shell\nbrew install postgresql\n```\n\n2. 创建数据库并启动\n\n```shell\n# 创建 postgresql 数据库\npnpm run pg:create\n# 启动\npnpm pg:start\n# 停止\npnpm pg:stop\n```\n\n3. 运行数据库迁移命令\n\n确保数据库与代码定义保持同步\n\n```shell\npnpm run migrate\n```\n\n查看当前应用的 Prisma 是否写入在当前项目根目录的 database/ 下:\n\n```shell\npsql \"postgresql://liaoyi:123456@localhost:5432/postgres\" -c \"show data_directory;\" -c\n\n# 如果显示如下，则正确\n# /Users/liaoyi/next-shopify-app/database\n# port = 5432\n```\n\n\u003c/details\u003e\n---\n\n### 本地开发\n\n[Shopify CLI](https://shopify.dev/apps/tools/cli) 会把你的本地项目连接到 Partner Dashboard 中的应用。\n它会提供环境变量、并行运行命令，并更新应用的 URL 以便更容易进行本地开发。\n\n你可以使用你偏好的包管理器进行本地开发。\n\n\n使用 pnpm：\n\n```shell\npnpm run dev-local\n```\n\n#### 使用 Docker 进行本地开发\n\n你也可以用 Docker 快速跑起来。它会为你设置并初始化 Postgres 数据库：\n\n```shell\ndocker-compose up\npnpm run migrate\n```\n\n#### Graphql-Codegen\n\n运行下面的命令会为 GraphQL 查询与 mutation 生成类型：\n\n```shell\npnpm run graphql-codegen\n```\n\n这会在你使用 Apollo Client 时提供类型支持，并在 IDE 中增强智能提示（IntelliSense）。\n\n## 部署\n\n你可以将该应用部署到你选择的任意托管服务。下面是部署到 Vercel 的基础流程：\n\n- 在 Shopify Partners Dashboard 中创建你的 Shopify 应用\n- 在 Vercel 中创建项目，并把 Shopify 应用的环境变量添加进去\n  - `SHOPIFY_API_KEY`\n  - `SHOPIFY_API_SECRET`\n  - `SCOPES`\n  - `HOST`\n  - 以及任意数据库连接串\n- 将你的 Shopify 应用配置为使用与 Vercel 部署一致的路由：\n  `/api/auth/callback` 与 `/api/auth`（包含你的部署域名）\n\nVercel 的构建配置通常使用默认的 Next.js 构建设置即可。\n\n你也应该使用“托管式（managed）”的 Shopify 部署方式，它会处理应用 scope 变更。\n\n```shell\npnpm run deploy\n```\n\n### 应用存储（Application Storage）\n\n该模板使用 Prisma 来存储与管理 session。更多 Prisma 配置方式请参考：\n[Prisma 文档](https://www.prisma.io/docs/getting-started/setup-prisma/start-from-scratch-typescript-postgres)。\n\n## 开发者资源\n\n- [Shopify 应用介绍](https://shopify.dev/apps/getting-started)\n- [应用鉴权](https://shopify.dev/apps/auth)\n- [Shopify CLI](https://shopify.dev/apps/tools/cli)\n- [Shopify API Library 文档](https://github.com/Shopify/shopify-api-node/tree/main/docs)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fliaoyio%2Fshopify-next-app","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fliaoyio%2Fshopify-next-app","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fliaoyio%2Fshopify-next-app/lists"}