Tutorial

Tutorial series · Shopify Headless × Agentic Coding

Shopify Headless environment and Agentic workflow setup

Shopify Hydrogen setup on React Router 7: connect a store, configure Dev MCP and CLAUDE.md, verify the agentic workflow, and deploy to Oxygen.

Create a Hydrogen (React Router 7) project, connect a store, configure Shopify Dev MCP and AI Toolkit, and deploy to Oxygen. Six steps set up an environment for development entirely through Claude Code.

Reading time
10 min
Updated
Open original report
Setup steps
6
Environment variables
7
Dev MCP tools
6
Additional Oxygen cost
$0
On this page

01Overview and goals

Stack components and the role of Dev MCP

This tutorial uses Shopify's official Hydrogen + Oxygen stack, with deployment, previews and rollbacks included at no additional cost on paid plans. Another headless option is a custom framework with Storefront API and the Headless channel.

Hydrogen migrated from Remix 2 to React Router 7 in 2025/5 (2025.5.0); the current skeleton (2026.4.4) uses React Router 7.16 and has removed @shopify/remix-oxygen. Most models' training data predates this migration, so code generated from an agent's memory can contain outdated imports and nonexistent fields. Shopify Dev MCP provides documentation search and GraphQL schema validation so agents use the current API.

The result is a Hydrogen project connected to a real store, with deployment on push and development entirely through Claude Code.

Scope:

  • Project creation

  • Store connection and environment variables

  • MCP configuration

  • Agent rules (CLAUDE.md)

  • Development loop

  • Oxygen deployment

Liquid themes and App development are outside the scope.

ComponentRole
HydrogenShopify's official headless framework, built on React Router 7
OxygenEdge deployment platform; no additional cost on paid plans (Basic and above, and Plus); unavailable for Starter and dev stores
Storefront APIGraphQL interface for product, cart and checkout data
Customer Account APIOAuth interface for customer login and account features
Shopify Dev MCPDocumentation search + GraphQL schema validation for agents; runs locally without authentication
Shopify AI ToolkitOfficial agent plugin with agent skills and Dev MCP; supports Claude Code

  1. Create a project

  2. Connect a store

  3. Configure MCP

  4. Define rules

  5. Agentic loop

  6. Deploy to Oxygen

「React Router is the open-source React-based framework that Hydrogen is built on top of.」 Hydrogen 建立在開源的 React Router 框架之上。

— shopify.dev · Hydrogen and Oxygen fundamentals

02Prerequisites

Version and account requirements

Node requirements: the skeleton's engines require ^22 || ^24, and Shopify CLI 4.4 requires >=22.12.0. The official getting-started page's "Node 16" information is outdated.

  • Not completed:

    Node.js 22 or 24: the minimum versions for Hydrogen skeleton and Shopify CLI; pin a version with nvm or mise.

  • Not completed:

    Claude Code: runs the agentic workflow; register MCP with its claude mcp add command.

  • Not completed:

    Git and a GitHub repo: Oxygen continuous deployment uses GitHub integration; connect the repo in step six.

  • Not completed:

    Shopify store admin access: creating a Hydrogen storefront requires access to Sales channels in admin; for agency work, this is usually a Client Transfer Store in your organization.

  • Not completed:

    Paid plan (for deployment): Oxygen has no additional cost on paid plans, but excludes Starter and dev stores; local development has no such restriction.

  • Not completed:

    A store is not immediately required: quickstart uses mock.shop sample data; steps one, three and four do not need a real store.

03Step one · Create a project

Hydrogen project creation

quickstart selects JavaScript, mock.shop sample data, no markets and a global h2 shortcut. Remove --quickstart to choose TypeScript or a styling option (Tailwind, CSS Modules, vanilla-extract or PostCSS); the CLI asks about each option.

bash
# quickstart:mock.shop 資料、JS、跳過所有詢問
npm create @shopify/hydrogen@latest -- --quickstart

# 或自選語言與樣式(CLI 逐項詢問)
npm create @shopify/hydrogen@latest

# 啟動本機開發伺服器(port 3000)
cd hydrogen-quickstart && npm run dev

Subsequent development primarily modifies the Starter's existing routes:

  • Home

  • Product pages

  • Collection pages

  • Cart

  • Account

  • Search

  • Blog

  • Policy pages

  • sitemap

  • robots.txt

04Step two · Connect a store

Store connection and environment variables

Create a Hydrogen storefront in store admin: Sales channels → Hydrogen → Create storefront. Shopify automatically generates environment variables for the storefront. Return to the project and run:

bash
# 連結本機專案與遠端 Hydrogen storefront
npx shopify hydrogen link

# 把 storefront 的環境變數寫進 .env
npx shopify hydrogen env pull

# 需要 Customer Account API(客戶登入)時,用 tunnel 啟動 dev
npx shopify hydrogen dev --customer-account-push
Environment variablePurpose
PUBLIC_STORE_DOMAINStore domain, such as example.myshopify.com
PUBLIC_STOREFRONT_API_TOKENPublic Storefront API token for client-side queries
PRIVATE_STOREFRONT_API_TOKENPrivate token for server-side queries; keep it confidential
PUBLIC_STOREFRONT_IDStorefront identifier
PUBLIC_CUSTOMER_ACCOUNT_API_CLIENT_IDCustomer Account API OAuth client ID
PUBLIC_CUSTOMER_ACCOUNT_API_URLCustomer Account API endpoint
SESSION_SECRETSecret used by React Router to sign session cookies

Code reads variables through context.env.<NAME>; manage production variables in admin under Storefront settings → Environments and variables. --customer-account-push opens a tunnel through tryhydrogen.dev and synchronizes callback URLs, which is required for local customer-login (OAuth) testing.

05Step three · Configure MCP

Shopify Dev MCP configuration

Shopify Dev MCP runs locally without authentication. Register it with one command for personal use; add --scope project for a team repo to write settings to .mcp.json in the project root. Commit the file to share it with the team; each member must approve it once on first use.

bash
# 官方指令:註冊 Shopify Dev MCP(個人 scope)
claude mcp add --transport stdio shopify-dev-mcp -- npx -y @shopify/dev-mcp@latest

# 團隊版:寫進專案 .mcp.json,可 commit 進版本庫
claude mcp add --transport stdio shopify-dev-mcp --scope project -- npx -y @shopify/dev-mcp@latest

# 官方 AI Toolkit plugin(含 agent skills;需 Node 18+)
claude plugin install shopify-ai-toolkit@claude-plugins-official
json
{
  "mcpServers": {
    "shopify-dev-mcp": {
      "command": "npx",
      "args": ["-y", "@shopify/dev-mcp@latest"]
    }
  }
}

Version 1.14.2 has six tools. All other tools require an initial learn_shopify_api call to obtain a conversationId; without it, they reject the request.

ToolPurpose
learn_shopify_apiLoads context for the selected API and issues a conversationId; the first step in each conversation
search_docs_chunksSearches shopify.dev documentation and code examples based on the user's request
validate_graphql_codeblocksValidates GraphQL against the actual schema to reject hallucinated fields; supports Admin, Storefront, Partner and Customer API
validate_themeValidates files in a theme directory
validate_theme_codeblocksValidates generated theme code blocks
validate_component_codeblocksValidates Storefront Web Components usage (early access; requires the STOREFRONT_WEB_COMPONENTS environment flag)

06Step four · Define rules

CLAUDE.md working rules

Shopify has not published an official CLAUDE.md template; the closest official resources are shopify.dev/llms.txt and AI Toolkit's agent skills. The following internal Tenten template makes the tools from step three part of the agent's required workflow:

markdown
# Hydrogen storefront — agent 工作規則

## Shopify API
- Shopify 相關任務先呼叫 shopify-dev-mcp 的 learn_shopify_api,
  再用 search_docs_chunks 查現行文件;不要憑記憶寫 API 用法。
- 任何 Storefront / Admin / Customer GraphQL 查詢,
  提交前必須通過 validate_graphql_codeblocks。

## 框架邊界
- 本專案是 React Router 7,不是 Remix:
  禁止 import @shopify/remix-oxygen 或 Remix 時代的套件。

## 環境與驗證
- 環境變數一律經 context.env 讀取;
  缺變數先跑 npx shopify hydrogen env pull,不要硬編。
- 開發伺服器 npm run dev(port 3000);
  GraphQL 手動驗證用 http://localhost:3000/graphiql。
- 改動完成後在瀏覽器實際走過受影響的頁面,再回報完成。

07Step five · Agentic loop

Agentic loop acceptance

Verify the environment with a real task. The standard loop is documentation lookup, query writing, schema validation, code changes and browser checks. validate_graphql_codeblocks rejects fields and operations that do not exist in the schema.

~/clients/store-a · claude code · shopify-dev-mcp 1.14

$ You › 商品頁加上「庫存低於 10 件時顯示急迫提示」,用 Storefront API 的庫存欄位。


# [shopify-dev-mcp] learn_shopify_api(api: storefront) → conversationId 取得
# [shopify-dev-mcp] search_docs_chunks("product variant inventory quantity")


claude: Claude › 文件確認 Storefront API 用 variant 的 quantityAvailable 欄位,
  需要在商品查詢裡展開 variants。先驗證查詢:


# [shopify-dev-mcp] validate_graphql_codeblocks → ✓ 查詢合法,無幻覺欄位


# [edit] app/routes/products.$handle.jsx — loader 加入 quantityAvailable,UI 加入條件提示
# [bash] npm run dev — port 3000 起動,無編譯錯誤


ok: ✓ 商品頁在庫存 < 10 的 variant 顯示急迫提示;GraphiQL 抽查兩個商品,數字與 admin 一致。

08Step six · Deployment

Oxygen deployment

For GitHub continuous deployment, choose Set up GitHub continuous deployment now in Sales channels → Hydrogen → Create storefront. Select the organization and repo, click Connect, then merge the workflow PR created by Shopify. Each subsequent push generates a preview deployment; the default branch maps to production.

Environment mapping: production uses the default branch; custom environments use specified branches; other branches use preview. Deployments are immutable and each has its own URL; changing environment variables in admin triggers redeployment of affected environments. Rollback is available only for production and custom environments.

bash
# 不走 GitHub 整合時,手動部署:
npx shopify hydrogen deploy

# GitHub 整合自動生成的 workflow 檔(merge 該 PR 即可,不要改動 id 行):
# .github/workflows/oxygen-deployment-0000000000.yml
#   內含 "#! oxygen_storefront_id: …" 釘選行,官方註明 Don't change

09Common errors and boundaries

Common errors and version boundaries

10Completion checks and next steps

Completion checks and next steps

Final state: the project connects to a real store; the agent has documentation search and schema validation; each push generates a preview. Check each item:

  • Not completed:

    Hydrogen runs locally: the result of step one; localhost:3000 renders correctly.

  • Not completed:

    .env has 7 variables and the dev server reads the real store: the result of step two.

  • Not completed:

    .mcp.json is committed and /mcp lists shopify-dev-mcp: the result of step three.

  • Not completed:

    CLAUDE.md rules take effect: the result of step four; the first Shopify action in a new session is learn_shopify_api.

  • Not completed:

    A task cycle passes GraphQL validation: the result of step five.

  • Not completed:

    push → preview, merge → production: the result of step six; both URLs have been opened.

Next steps

1. Environment templates

CLAUDE.md, .mcp.json and workflow files are the same across client projects; collect them in a template repo for cloning into new projects.

2. Agentic commerce

The UCP system at shopify.dev/docs/agents (Catalog, Cart, Checkout and Order MCP) is a store-side interface for shopping agents to operate the store. It complements this development-side workflow.

3. Browser checks in the QA loop

Add chrome-devtools-mcp or @playwright/mcp to .mcp.json so the agent can verify page behavior.

Further documentation

① Hydrogen getting started (shopify.dev): Official scaffolding and initial setup.

② Shopify Dev MCP (shopify.dev): Official installation commands and instructions for each agent platform.

③ Claude Code MCP documentation (code.claude.com): Scope rules, .mcp.json format and approval mechanisms.

「Validates GraphQL code blocks against the Shopify GraphQL schema to ensure they don't contain hallucinated fields or operations.」 對 Shopify GraphQL schema 驗證程式碼,確保沒有幻覺欄位與操作。

— @shopify/dev-mcp · validate_graphql_codeblocks 工具說明

References