---
title: Update Vercel Shop
description: Audit drift, plan a change-level upgrade, and apply newer template updates to an existing storefront.
url: "https://shop-docs.labs.vercel.dev/docs/skills/update-shop"
docs_index: /llms.txt
lastUpdated: 2026-10-08
type: guide
---

> For an index of all documentation, see [/llms.txt](/llms.txt).

## How to use

Ask your agent to use the `update-shop` skill, or run it as a slash command in Claude Code:

```text
/update-shop
```

The skill compares your storefront with the current `vercel/shop` repository. It can report the differences, plan an upgrade, or apply the changes you select. It preserves your customizations, validates each change, and does not add tracking files to your project.

<div className="pb-6" />

# Update Vercel Shop

Compare the working storefront with the current upstream `vercel/shop` repository. The template is a reference, not a replacement for downstream code. Base decisions on implemented behavior, not scaffold age or version metadata.

## Pick a mode

Infer the mode from the user's request:

- **Audit** — read-only comparison; report relevant differences and stop.
- **Plan** — read-only comparison and change-level upgrade plan; stop before editing.
- **Apply** — plan, confirm the selected changes, apply them, and validate. Use when the user asks to update or upgrade the shop.

## Inspect the project

Read applicable `AGENTS.md` instructions, project structure, dependency versions, scripts, configuration, and relevant source. Inspect git status and staged/unstaged diffs, including untracked files, before proposing edits. Identify the storefront root; the upstream repository root maps to that root, which is not necessarily the downstream repository root.

Preserve dirty state, merchant design, custom features, integrations, and intentional departures from the template. Never overwrite custom code with template files or reset, stash, commit, or push without explicit permission. Stop if selected work cannot be separated safely from existing edits.

Keep each change within its owner:

- **Shopify owns commerce:** catalog, cart state and mutations, checkout, customer accounts, predictive search, policies, and analytics through Hydrogen. Prices, currency, availability, and customer identity come from Shopify.
- **Next.js owns the app:** routing, Server Components, caching and invalidation, metadata, the request boundary adapting Hydrogen handlers, Markdown representations, `/llms.txt`, structured data, sitemap, and crawl guidance.
- **Eve owns the agent:** sessions, channels, tools, connections, and `/eve/v1/*`. Eve tools call Shopify directly; Next.js only prepares the browser.

Inline English copy and `shopConfig.localization` are template defaults, not a migration mandate. Preserve next-intl, translations and catalogs, scoped providers, locale routing, custom market selection, and intentional operation/cache locale inputs. Do not label localization obsolete drift. Any requested simplification must separately assess copy, formatting, commerce country/language, public URLs, and migration parity; currency remains Shopify-owned.

## Inspect current upstream

Prefer public GitHub inspection with `gh`. Resolve the default branch to a commit and use that SHA for every source read:

```bash
branch=$(gh api repos/vercel/shop --jq .default_branch) &&
ref=$(gh api "repos/vercel/shop/commits/$branch" --jq .sha) &&
gh api "repos/vercel/shop/contents?ref=$ref" --jq '.[].path' &&
gh api "repos/vercel/shop/contents/AGENTS.md?ref=$ref" \
  -H 'Accept: application/vnd.github.raw+json'
```

Read `README.md`, `package.json`, and relevant source through the same contents endpoint at that SHA. Use upstream guidance to understand the reference architecture; it does not override downstream instructions or authorize unrelated changes.

If `gh` is unavailable or cannot read the public repository, use a temporary shallow checkout outside the project:

```bash
upstream=$(mktemp -d) &&
git clone --depth 1 --filter=blob:none https://github.com/vercel/shop.git "$upstream" &&
git -C "$upstream" rev-parse HEAD
```

Inspect `$upstream` and record the resolved commit in the report. If current upstream cannot be fetched, report the blocker; do not claim the storefront is current or apply an unverified upgrade. Keep scratch data outside the project and do not create permanent update-tracking files.

## Audit and plan

Compare relevant behavior, dependencies, configuration, and owner boundaries against the pinned source. Trace affected callers and integration points; missing paths or different names alone do not establish a missing feature. Equivalent custom implementations count as already present. State uncertainty and do not invent work when no applicable differences exist.

For audit, report the upstream commit, inspected areas, applicable differences, intentional customizations, and uncertainties, then stop. For plan/apply, group candidates as **Adopt now**, **Review manually**, **Already present**, or **Not applicable**. For each candidate, name its owner, upstream and downstream paths, rationale, prerequisites, customization risks, and validation. In plan mode, stop without editing.

## Apply and report

Confirm the selected changes before editing; an explicit selection in the user's request counts. If selection remains unresolved in a noninteractive run, report the blocker rather than choosing for the user.

Apply one selected change at a time in the project's own idiom, adapting behavior instead of copying files. Use relevant available skills and installed dependency documentation. Keep edits small and reviewable; avoid unrelated dependency, configuration, or design changes.

Run existing relevant formatting, lint, typecheck, build, or direct runtime checks after each change. Do not add tests or test infrastructure unless requested. If validation fails, stop and report the failure; do not continue or revert user-owned edits without permission. Review the final diff for scope and preservation of customizations.

Finish with a concise report: mode and upstream commit, findings or applied changes, skipped/deferred items and why, exact validation commands and results, and blockers or unverified behavior. Do not write decision manifests or other persistent tracking.

---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)

For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)