# Vercel Shop documentation > Documentation for Vercel Shop — an agent-native, fast-by-default Shopify storefront built on Next.js. ## When to use Vercel Shop - Category: Commerce - Audience: Storefront developers, AI agents extending storefronts Common use cases: - Build a Shopify storefront on Next.js - Extend a storefront with AI agents and skills - Serve storefront content to AI agents via content negotiation ## Documentation --- title: Introduction description: Learn about the Vercel Shop template and what it offers. url: "https://shop-docs.labs.vercel.dev/docs" docs_index: /llms.txt lastUpdated: 2026-09-07 type: overview --- > For an index of all documentation, see [/llms.txt](/llms.txt). Vercel Shop gives you a production-ready Shopify storefront built with Next.js. Connect Shopify, run the storefront, then adapt it to your business with your team or a coding agent. The template includes product pages, collections, search, and a cart backed by Shopify. Customer accounts and the shopping assistant are optional. Configure webhooks to refresh cached products and collections when you edit them in Shopify. Start with [Getting Started](/docs/getting-started). For the design goals behind the template, read [Why Use This](/docs/why-use-this). Set up Shopify, create a project, and run the storefront locally. Extend and customize the storefront with Claude Code or Cursor. Decide whether an owned Next.js storefront fits your team. --- 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) --- title: Why Use This description: An owned Shopify storefront with Next.js, Vercel, and guidance for agent-assisted development. url: "https://shop-docs.labs.vercel.dev/docs/why-use-this" docs_index: /llms.txt lastUpdated: 2026-09-07 type: overview --- > For an index of all documentation, see [/llms.txt](/llms.txt). Vercel Shop gives your team an owned storefront without making you rebuild the foundation of headless commerce. Shopify manages your catalog and checkout. Next.js and Vercel provide the storefront framework and hosting. Product pages, search, collections, and a cart are included, so your team can focus on the shopping experience. The code lives in your repository. You can inspect it, change it, and give coding agents clear project conventions for future work. That makes agent-assisted development practical without giving up control of the storefront. Start with a working store, then invest in the choices only your team can make. --- 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) --- title: "AEO & GEO" description: How the storefront makes itself legible to AI answer engines and generative search, with built-in content negotiation, structured data, and discovery surfaces. url: "https://shop-docs.labs.vercel.dev/docs/anatomy/aeo-geo" docs_index: /llms.txt lastUpdated: 2026-09-16 type: guide --- > For an index of all documentation, see [/llms.txt](/llms.txt). **Answer Engine Optimization (AEO)** and **Generative Engine Optimization (GEO)** help AI services understand and cite your storefront. The template provides machine-readable product and collection content without changing the pages shoppers visit. ## Make storefront content readable to AI The home page, product, collection, and search URLs return structured Markdown when a client requests `text/markdown`. Normal browser requests continue to receive HTML from the same URLs. No setup is required. The storefront also publishes `/llms.txt`, a concise index for AI agents. It links to search, up to 50 collections, the sitemap, crawl guidance, and the storefront's UCP profile rather than duplicating the full catalog. The [sitemap](/docs/anatomy/sitemap) remains the complete URL inventory. Markdown explains a product; it does not sell it. Live per-variant availability, cart, and checkout for agents come from Shopify's Universal Commerce Protocol (UCP) endpoints, which the storefront forwards at `/.well-known/ucp` and `/api/ucp/mcp`. Product Markdown points agents there instead of repeating per-variant stock. Markdown content uses the deployment's configured Shopify country and language. If you add [Shopify Markets](/docs/skills/enable-shopify-markets), make sure AI-readable content uses the same market as the corresponding shopper page. ## Included discovery surfaces | Surface | Outcome | | -------------------------------- | ------------------------------------------------------------------------------ | | Markdown responses | Gives AI clients clean product, collection, and search content | | Schema.org data | Describes products, breadcrumbs, and the organization | | [Sitemap](/docs/anatomy/sitemap) | Lists storefront content for crawlers | | Crawl guidance | Points crawlers to the sitemap and blocks faceted collection URLs | | `/llms.txt` | Gives AI agents a concise storefront index | | Social metadata | Supplies route-specific titles, descriptions, images, prices, and availability | Markdown responses include the facts needed to interpret each page: - **Products** — brand, category, a one-line summary, price or price range with compare-at price, product-level availability, description, options, images, and links to the shopper page and UCP profile. - **Collections** — description, active and available filters, products, pagination, image, and SEO metadata. - **Search** — query, collection scope, filters, products, and pagination. ## What’s next Keep `/llms.txt` concise and use the sitemap for exhaustive discovery. Common extensions include Markdown responses for additional page types, localized discovery content, and public metaobject content. Include only facts an agent needs to identify, compare, or link to that content. --- 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) --- title: Agent description: Enable product discovery, store questions, and cart updates through conversation. url: "https://shop-docs.labs.vercel.dev/docs/anatomy/agent" docs_index: /llms.txt lastUpdated: 2026-09-15 type: guide prerequisites: - /docs/getting-started --- > For an index of all documentation, see [/llms.txt](/llms.txt). Shop Agent helps shoppers find products, choose options, ask store questions, and manage their cart through conversation. It is **disabled by default**. The storefront works without it, and the chat control stays hidden until you enable it. Customer sign-in is not required. ## Enable Shop Agent Shop Agent uses your storefront's existing Shopify connection. It runs on [Eve](https://eve.dev) with OpenAI GPT-5.6 Luna (Fast) through [Vercel AI Gateway](https://vercel.com/ai-gateway). 1. Set `agent.isEnabled` to `true` in `lib/config/index.ts`. The chat button floats in the bottom corner; move it by rendering `AgentButton` elsewhere in the layout. 2. Configure AI Gateway access. Vercel deployments can use deployment identity authentication. For local development or other hosts without that authentication, set `AI_GATEWAY_API_KEY` in your server environment. Use `.env.local` for local values and keep the key server-only. See [Environment Variables](/docs/reference/env-vars#shop-agent). 3. Run `pnpm dev`, open Shop Agent, and ask for a product from your store. The reply should show product cards you can open or ask about. Before allowing public traffic, review [privacy and usage limits](#privacy-and-usage-limits). On Vercel, deploy the storefront with the setting and Gateway access configured; you do not need a separate agent deployment. ### Local production For a local production build, run `pnpm build:agent && pnpm build`. Then run `pnpm exec eve start --port 4274` and `pnpm start` in separate terminals. Use `pnpm dev` for ordinary development. ## Shopper experience Shoppers can: - Find products and collections, narrow results by color or size, and choose variants. - Get product recommendations and answers about store policies. - Add items, change quantities, remove items, and add an order note. Product and policy answers use Shopify data. Keep your catalog and store policies up to date so shoppers can get useful answers. ### One cart, with the shopper in control Chat shares the storefront's [cart](/docs/anatomy/cart). Confirmed changes show the updated cart in the conversation. The assistant cannot place orders or process payments; shoppers use the checkout button. New messages and checkout wait while the assistant is working or confirming the cart in that browser tab. If confirmation fails, use **Refresh cart**. This checks the cart without repeating the change. Wait for the response before checking out in another tab. A cart change may finish after a response is stopped or interrupted. Check the cart before asking again, especially after a timeout or connection failure. ### Continue a conversation or start over The conversation and draft can be restored after navigation or reload in the same browser. Use **Stop** to interrupt a response or **Clear chat** to start over. Clear waits for an active response to stop; if it cannot confirm that, it keeps the conversation for retry. Clearing chat does not empty the cart. Long conversations are summarized automatically so they stay within the model's context. Conversations expire after 30 days; if one has expired, clear it to start a new one. ## Privacy and usage limits Once enabled, chat is publicly accessible and messages can incur model charges. The template does not cap tokens per conversation; control cost where traffic enters instead. Add deployment-level rate limits and Gateway spending controls appropriate to your traffic. Bot protection is **disabled by default**. For Vercel deployments, enable `botid.isEnabled` in [Shop Configuration](/docs/reference/shop-config) so automated traffic is rejected before it reaches the model. Bot protection does not replace access controls or spending limits. Customer sign-in does not make chat history private. The default setup does not restrict a conversation to its original shopper: anyone with its conversation ID may be able to read or control it. Do not share conversation IDs. Add authenticated conversation ownership before using chat for private account or support data. Eve stores conversations on the server, and conversation content is sent to the model provider. Clearing chat or conversation expiry does not guarantee deletion of those records. Configure retention and access policies, and explain to shoppers how their messages are handled. The assistant receives a summary of cart items rather than gift-card recipient details. Personal information shoppers type into chat still reaches the model provider. Avoid requesting sensitive information that is not needed for shopping. ## What’s next Adapt the tone, product presentation, and recommendations to your store. Add store-specific guidance while keeping Shopify as the source of prices and availability. Choose a model that balances response quality, speed, and cost. --- 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) --- title: Authentication description: Enable Shopify customer sign-in, order history, profile details, and saved addresses. url: "https://shop-docs.labs.vercel.dev/docs/anatomy/authentication" docs_index: /llms.txt lastUpdated: 2026-09-13 type: guide --- > For an index of all documentation, see [/llms.txt](/llms.txt). The template includes opt-in customer authentication through Shopify Customer Accounts. Signed-in customers can manage their profile and addresses, review orders, and continue to checkout with their customer identity. Authentication is disabled by default. The storefront remains guest-only until you complete the setup below. ## Configure customer accounts Set `auth.isEnabled` to `true` in `lib/config/index.ts` and configure these environment variables: ```bash CUSTOMER_ACCOUNT_SESSION_SECRET="your-session-secret-here" SHOPIFY_CUSTOMER_ACCOUNT_API_CLIENT_ID="shp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" SHOPIFY_CUSTOMER_ACCOUNT_API_CLIENT_SECRET="your-customer-account-client-secret-here" ``` Shopify provides the confidential client ID and client secret. Generate the session secret yourself: ```bash openssl rand -base64 32 ``` Keep both secrets server-only and identical across every instance of a deployment. Rotating the session secret signs out all customers. A build with authentication enabled fails when the session secret, client ID, or client secret is missing. Customer Account OAuth requires a public HTTPS origin. For local testing, open the storefront through a public HTTPS tunnel. In Shopify Admin: 1. Go to **Settings → Customer accounts → Edit**. 2. Choose **Customer accounts**, then save. 3. Install the **Headless** sales channel. 4. Go to **Sales channels → Headless → your storefront → Customer Account API**. 5. Copy the confidential client ID and client secret. 6. Add `https://YOUR_DOMAIN/account/authorize` as the callback URI. 7. Add `https://YOUR_DOMAIN/` as the logout URI. 8. Set `SHOPIFY_CUSTOMER_ACCOUNT_API_CLIENT_ID` and `SHOPIFY_CUSTOMER_ACCOUNT_API_CLIENT_SECRET` to the copied values. 9. Confirm `NEXT_PUBLIC_SHOPIFY_STORE_DOMAIN` identifies the same store. Shopify does not support wildcard callback or logout URIs. Register every production, preview, and tunnel origin that needs authentication. See [Environment Variables](/docs/reference/env-vars) for the full variable reference. ## Customer experience Customers sign in at `/account/login` and sign out through `/account/logout`. The storefront provides: - `/account/profile` for name and email details - `/account/orders` and `/account/orders/[id]` for order history and details - `/account/addresses` for creating, editing, deleting, and choosing a default address Sessions use encrypted, HttpOnly cookies rather than browser-readable storage. Expired access tokens refresh through `/account/refresh`. Logout ends both the storefront session and the Shopify sign-in session. When authentication is enabled, the cart follows the customer session. Signing in attaches the browser cart when possible, and checkout can carry the customer's saved details. Cart synchronization is best-effort; an authentication redirect still completes if cart synchronization fails. Customer Account API data is personalized and is not publicly cached. > **Security requirements:** Never expose access, refresh, or ID tokens to browser-readable storage. Keep logout as a same-origin `POST`. If sign-in redirects fail, compare the deployed origin, callback URI, logout URI, store domain, client ID, and client secret character for character. Failed callbacks return to the storefront instead of restarting sign-in. ## What’s next You can change the account navigation, add a dashboard, or expose more Customer Account API data such as store credit or subscriptions. Validate additions against the Customer Account API schema, which differs from the Storefront API, and keep private customer data behind authentication. See [Proxy](/docs/anatomy/proxy) for the storefront's request-routing role in customer account URLs. --- 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) --- title: Cart description: How shoppers add products, manage quantities and discounts, and continue to Shopify checkout. url: "https://shop-docs.labs.vercel.dev/docs/anatomy/cart" docs_index: /llms.txt lastUpdated: 2026-09-13 type: guide --- > For an index of all documentation, see [/llms.txt](/llms.txt). Shoppers use one Shopify cart across product pages, the cart drawer, and the full cart page. [Shop Agent](/docs/anatomy/agent) uses that same cart when enabled. The standard cart is ready to use without additional setup. The storefront remembers it in the same browser for up to 14 days. ## Shopper experience Shoppers can add products, change quantities, remove items, apply discount codes, and proceed to checkout. The cart drawer is available throughout the storefront, and `/cart` provides a full-page view. Quantity changes appear immediately while Shopify confirms them. If Shopify rejects a change, the cart returns to its confirmed state and shows the relevant error. Prices and totals indicate when they are still updating. Errors for a particular item appear alongside it. Checkout stays unavailable until pending cart changes are confirmed. If checkout cannot start, an inline message lets the shopper try again without rebuilding the cart. The cart displays discounts and sale pricing confirmed by Shopify. Bundles remain grouped so shoppers can understand which products belong together. Some bundle items cannot be edited individually. When [customer authentication](/docs/anatomy/authentication) is enabled, signing in can attach the browser cart to the customer so checkout can use their saved details. Customer sign-in is optional and disabled by default. ## Important limits - Cart recovery depends on the browser retaining its cookie and Shopify still returning the cart. Clearing browser data can start a new cart sooner than 14 days. - Shopify determines inventory, prices, discounts, and which changes are allowed. An item being in the cart does not guarantee it will remain available at checkout. - A cart change may finish after a chat response is interrupted. Check the cart before repeating the request. - Preserve gift-card recipient details and bundle information when customizing the cart so that checkout receives everything needed to fulfill the order. If you need to attribute cart activity to a particular Headless storefront, set `NEXT_PUBLIC_SHOPIFY_STOREFRONT_ID`. See [Environment Variables](/docs/reference/env-vars#optional). ## What’s next Add gift messages, personalization, or other order details to suit your store. Make sure that information reaches checkout, and keep Shopify responsible for prices and availability. Custom bundle flows should make clear which items shoppers can change together or separately. --- 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) --- title: Footer description: The storefront footer - copyright, Shopify policy links, social links, and optional menu columns. url: "https://shop-docs.labs.vercel.dev/docs/anatomy/footer" docs_index: /llms.txt lastUpdated: 2026-09-07 type: guide --- > For an index of all documentation, see [/llms.txt](/llms.txt). The footer appears on every page. By default, it shows your store name and links to every policy configured in Shopify. Social links and menu columns are optional. ## Publish store policies Add and maintain policies in Shopify Admin. The footer automatically links each configured policy using the deployment's configured Shopify language. Policies without content do not appear, so there is no separate list to maintain. Supported policy pages include contact information, legal notice, privacy, refunds, shipping, terms of sale, and terms of service. ## Choose what else to show - **Copyright** — uses the configured store name and omits the year by default. - **Social profiles** — hidden until you add profile URLs. Supported services are Facebook, Instagram, X, YouTube, TikTok, Pinterest, LinkedIn, and GitHub. - **Menu columns** — use the [`enable-shopify-menus`](/docs/skills/enable-shopify-menus) skill to add links from a Shopify footer menu. ## What’s next Common additions include a Shopify-managed link menu, a newsletter signup, payment or trust marks, and market or language controls. Keep the footer focused on destinations shoppers may need from any page. --- 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) --- title: Translations description: Customize storefront copy for one deployment, then add translated languages or Shopify Markets when needed. url: "https://shop-docs.labs.vercel.dev/docs/anatomy/i18n" docs_index: /llms.txt lastUpdated: 2026-09-07 --- > For an index of all documentation, see [/llms.txt](/llms.txt). The default storefront serves one deployment with clean URLs such as `/products/shoe`. It keeps copy alongside components rather than using a translation library. next-intl and language switching are optional upgrades. ## Customize storefront copy Edit shopper-facing text in the component that displays it. The default storefront has no central translation catalog; labels, messages, and accessibility text are kept with the interface they describe. After changing a quantity message, check zero, one, and multiple items. Include loading states, empty states, errors, and accessibility labels when reviewing copy. ## Set the deployment context Set `shopConfig.localization` in `lib/config/index.ts` for the deployment: ```ts localization: { country: "US", language: "EN", locale: "en-US", }, ``` Country and language configure Shopify requests. Locale controls display formatting, such as numbers and dates. Prices use the currency returned by Shopify; changing a formatting locale does not convert a price. These settings do not translate the storefront's own labels. Edit copy separately, and publish translated product or editorial content in Shopify when needed. The default does not negotiate a shopper's locale or add locale prefixes to URLs. ## What’s next Use [Enable i18n](/docs/skills/enable-i18n) to add next-intl, translated catalogs, and locale-prefixed URLs without changing the commerce country. Use [Enable Shopify Markets](/docs/skills/enable-shopify-markets) for regional commerce context and Shopify-controlled pricing. Both upgrades must preserve existing translations and routing in stores that are already localized. Add a language to navigation only when its fixed copy, interactive messages, plurals, formatting, and error states are ready. A copy-language selector and a commerce-country selector solve different problems; changing language alone should not move a shopper into another market. --- 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) --- title: Navigation description: The storefront navigation system - desktop and mobile menus, search, cart access, and optional Shopify-managed links. url: "https://shop-docs.labs.vercel.dev/docs/anatomy/navigation" docs_index: /llms.txt lastUpdated: 2026-09-13 type: guide --- > For an index of all documentation, see [/llms.txt](/llms.txt). The storefront provides desktop and mobile navigation, predictive search, and cart access. Links are static by default. Use [`/vercel-shop:enable-shopify-menus`](/docs/skills/enable-shopify-menus) when merchants need to manage them in Shopify. ## Help shoppers move through the store On desktop, a sticky header shows the logo, primary links, search, and cart. On mobile, primary links move into a menu while search and cart remain in the header. The mobile menu closes after a shopper selects a link. Search opens as a dialog. It shows suggestions and matching products as the shopper types, links directly to products, and offers a full results page. It closes after navigation, Escape, or an outside click. Set `search.isEnabled` to `false` in [Shop Configuration](/docs/reference/shop-config) to remove the search button and dialog; the `/search` results page stays available. The cart badge shows the current item count and opens the cart. ## Choose how links are managed The default storefront includes a single Shop link. This is suitable for a small catalog or a navigation structure managed in code. Use the [`enable-shopify-menus`](/docs/skills/enable-shopify-menus) skill to let merchants manage desktop links, mobile links, and footer columns through Shopify Navigation. Menus can contain up to three levels. An optional mobile bottom bar appears only when you add an action, such as an agent button. ## What’s next Enable [Authentication](/docs/anatomy/authentication) to show the built-in customer-account link. Other additions include Shopify-managed menus, promotional bars, and richer desktop navigation for large catalogs. Keep search and cart access easy to reach on every screen size. --- 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) --- title: Product Card description: "The shared tile that displays a product's image, title, price, and availability across the storefront." url: "https://shop-docs.labs.vercel.dev/docs/anatomy/product-card" docs_index: /llms.txt lastUpdated: 2026-09-07 type: guide --- > For an index of all documentation, see [/llms.txt](/llms.txt). Product cards give shoppers a consistent way to recognize and compare products. They appear on the home page, collection and search pages, related-product sections, and agent results. A visual change affects every use. ## Information shoppers see Each card links to the product and shows its image, title, and price. Products with a price range show both bounds. A single discounted price can show the original price and a discount badge; ranges do not show a discount because discounts may differ by variant. When a shopper applies one color filter, collection and search cards use the image assigned to that color's first selectable variant and link to its selected options. Assign an image to each color variant in Shopify so filtered cards can show the matching merchandise. Cards fall back to the product image when the matching variant has no image. Unavailable products keep their image visible under an out-of-stock label. Products without an image show a placeholder instead of a broken image. Loading, empty, and loaded states reserve the same square space so grids remain stable. The featured style adds an “Assistant's pick” badge and stronger image treatment. Standard grids use the default style. ## Decide whether cards should support purchasing The default card is for discovery. Shoppers open the product page to choose variants and add an item to the cart. Products with required options usually need the full product page. Add purchasing controls to cards only when shoppers can choose safely from the information shown. ## What’s next Common additions include alternate image proportions, a second image on hover, review summaries, variant swatches, and quick add. Keep cards easy to scan, and add purchasing controls only when shoppers have enough information to choose safely without opening the product page. --- 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) --- title: Proxy description: Add routing rules without interrupting Shopify services or storefront pages. url: "https://shop-docs.labs.vercel.dev/docs/anatomy/proxy" docs_index: /llms.txt lastUpdated: 2026-09-13 type: guide --- > For an index of all documentation, see [/llms.txt](/llms.txt). The storefront's [Next.js proxy](https://nextjs.org/docs/app/getting-started/proxy), also called middleware, keeps Shopify's service routes separate from storefront pages and custom APIs. The default routing works without additional setup. ## What it handles The proxy supports cart updates, search suggestions, Shopify API access, and Shopify-compatible commerce endpoints. This includes legacy cart URLs and Shopify's business profile at `/.well-known/ucp`. Customer sign-in routes are available only when you enable [customer authentication](/docs/anatomy/authentication). Shop Agent is enabled separately and uses `/eve/v1/` for conversations. Ordinary pages continue to Next.js. Home, product, collection-detail, and search pages can also return Markdown for clients that request it. See [Routes](/docs/reference/routes) for page URLs and service endpoints. Custom API routes are not intercepted unless they match a route explicitly reserved for an integration. ## Add routing without creating conflicts When extending `proxy.ts`, match only the routes an integration needs. Do not redirect every `/api/` request or claim all `/agent/` paths: Shopify and Shop Agent serve different endpoints. Keep Shopify routing ahead of locale negotiation, experiments, and request-dependent redirects. A cart update or Shopify API request should not be redirected to a language-prefixed page. Use Next.js configuration for fixed redirects, such as moving an old page to a new URL. Use the proxy when the destination depends on the incoming request. ## What’s next Add locale routing with [Shopify Markets](/docs/skills/enable-shopify-markets) or [i18n](/docs/skills/enable-i18n), or introduce request-dependent experiments and redirects. Keep those rules scoped to storefront pages so cart, sign-in, and API requests continue to work. --- 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) --- title: Sitemap description: A sitemap index and paged child sitemaps for storefront content managed in Shopify. url: "https://shop-docs.labs.vercel.dev/docs/anatomy/sitemap" docs_index: /llms.txt lastUpdated: 2026-09-07 type: guide --- > For an index of all documentation, see [/llms.txt](/llms.txt). The storefront publishes `/sitemap.xml` as the single discovery URL for products, collections, Shopify Pages, blogs, articles, and configured policies. Crawl guidance points search engines to this index. ## What the sitemap includes | URL | Contents | | ------------------------------ | ----------------------------------------- | | `/sitemap.xml` | Index of every child sitemap | | `/sitemap/static.xml` | Home page and configured Shopify policies | | `/sitemap/products-{n}.xml` | Up to 250 products per page | | `/sitemap/collections-{n}.xml` | Up to 250 collections per page | | `/sitemap/pages-{n}.xml` | Up to 250 Shopify Pages per page | | `/sitemap/blogs-{n}.xml` | Up to 250 Shopify blogs per page | | `/sitemap/articles-{n}.xml` | Up to 250 Shopify articles per page | Shopify determines how many pages each content type needs. The storefront lists every page in the index, so crawlers need only `/sitemap.xml`. ## Freshness limits Product and collection webhooks refresh affected sitemap entries. Creating or deleting those resources also refreshes the relevant sitemap listing. See [Webhooks](/docs/anatomy/webhooks). The template's webhook handler does not refresh Pages, blogs, articles, or policies. Their sitemap entries can remain cached until revalidation. If a publishing change must appear immediately, refresh the sitemap as well as the page content. ## What’s next Shopify's sitemap API also supports metaobjects, but the template does not include them. Add that resource type only when metaobjects have public storefront URLs that search engines should discover. Stores with rich media may also add image or video sitemap data for content that search engines cannot discover reliably from the page itself. --- 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) --- title: Webhooks description: Refresh supported storefront content when Shopify products, collections, or metaobjects change. url: "https://shop-docs.labs.vercel.dev/docs/anatomy/webhooks" docs_index: /llms.txt lastUpdated: 2026-09-07 type: guide --- > For an index of all documentation, see [/llms.txt](/llms.txt). Shopify webhooks make supported Admin changes appear on the storefront without waiting for cached data to expire. The template accepts Shopify notifications at `POST /api/webhooks/shopify` and refreshes the affected product, collection, recommendation, sitemap, or metaobject content. Webhooks are disabled by default. Without `SHOPIFY_WEBHOOK_SECRET`, the endpoint returns `404` and Shopify changes appear only after cache expiry or a redeploy. ## Set up Shopify webhooks 1. Open **Shopify Admin → Settings → Notifications → Webhooks**. 2. Set the destination to `https://your-domain.com/api/webhooks/shopify`. 3. Choose **JSON** as the format. 4. Register the product, collection, and metaobject topics you need. 5. Copy the webhook signing secret into `SHOPIFY_WEBHOOK_SECRET` for that environment. ```bash SHOPIFY_WEBHOOK_SECRET="your-webhook-secret-here" ``` Register these supported topics: - `products/create`, `products/update`, and `products/delete` - `collections/create`, `collections/update`, and `collections/delete` - Metaobject create, update, and delete topics You can register only the topics your store uses. An unregistered topic simply means those changes wait for normal cache expiry. See [Environment Variables](/docs/reference/env-vars) for the full variable reference. ## Behavior and security Every configured request must carry a valid Shopify signature. Missing, malformed, or incorrect signatures return `401`. The handler rejects the request before using its topic or payload. Product notifications refresh the affected product wherever it appears, including recommendations and sitemap content. Product creation and deletion also refresh catalog membership. Collection notifications refresh the affected collection and collection listings. Collection creation and deletion also refresh collection membership and sitemap content. Metaobject notifications refresh metaobject-backed content only when your custom reads participate in the template's metaobject invalidation behavior. The base template does not read metaobjects by default. ## Limits The included handler does not refresh inventory-level changes. Stock updates therefore appear at cache expiry unless another supported product webhook arrives or you add a live inventory strategy. This handler does not refresh Online Store pages, blogs, articles, or store policies. Those edits wait for cache revalidation unless you arrange a separate refresh. See [Content pages](/docs/anatomy/pages/content) for publishing guidance. Navigation menu edits are also outside this handler. Malformed product or collection update payloads cannot identify a specific resource, so they do not refresh the full catalog. Valid Shopify deliveries include the expected identifiers. After registering a topic, use **Send test notification** in Shopify Admin and confirm the delivery succeeds before relying on it for storefront freshness. ## What’s next Add a topic only when Shopify offers a webhook for the resource and the storefront has a safe way to refresh the affected data. Prefer targeted refreshes for frequently changing catalog data. Use broader refreshes only when an event cannot be scoped or after an intentional bulk change. --- 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) --- title: WebMCP description: Experimental browser agent tools that expose storefront search and cart actions through the proposed WebMCP API. url: "https://shop-docs.labs.vercel.dev/docs/anatomy/webmcp" docs_index: /llms.txt lastUpdated: 2026-09-13 type: guide --- > For an index of all documentation, see [/llms.txt](/llms.txt). WebMCP is an **experimental** browser API for exposing structured tools to AI agents running in or alongside a browser. The storefront can expose Shopify catalog search and cart actions through this API. The integration is disabled by default. The proposed API may change or be removed, and unsupported browsers receive no fallback interface. ## Decide whether to enable it Enable WebMCP only for active testing. When enabled in a supporting browser, Shopify registers storefront tools that agents can discover and call with structured inputs. Cart actions use the same cart the shopper sees. Shopify defines and hosts the available tools. The template cannot select or change individual tools, and Shopify may update them independently. WebMCP and Shopify analytics are separate choices. Enabling WebMCP does not enable Shopify page-view reporting. ## Test locally For local testing, use a Chrome build that exposes the WebMCP testing flag: 1. Check that your Chrome build supports WebMCP testing. 2. Open `chrome://flags/#enable-webmcp-testing`. 3. Enable **WebMCP for testing**, then relaunch Chrome. 4. Set `browserAgents.webmcp.isEnabled` to `true` in `lib/config/index.ts`, then load the site. 5. Use a WebMCP inspector or a connected browser agent to list and invoke the registered tools. 6. Confirm that search returns structured catalog results and cart actions update the shopper's cart. Browser support and origin-trial requirements can change. Check your browser's current WebMCP documentation before enabling it on a public deployment. Leave the feature disabled for shoppers unless you accept the compatibility and stability limits of an experimental API. --- 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) --- title: Extending with Agents description: Use coding agents like Claude Code, Cursor, and Codex to personalize and extend your storefront. url: "https://shop-docs.labs.vercel.dev/docs/getting-started/extending-with-agents" docs_index: /llms.txt lastUpdated: 2026-09-07 type: guide prerequisites: - /docs/getting-started --- > For an index of all documentation, see [/llms.txt](/llms.txt). Use a coding agent to change the storefront while following the template's conventions and verification steps. ## Set up the agent `create-vercel-shop` installs project plugins for Vercel Shop, Next.js, Vercel, and Shopify. To install those plugins in an existing project without downloading the template, run: ```bash npx create-vercel-shop@latest --no-template ``` If the plugins are missing, install them directly: ```bash npx plugins add vercel/shop --scope project --yes npx plugins add vercel/vercel-plugin --scope project --yes npx plugins add Shopify/shopify-ai-toolkit --scope project --yes ``` Use an agent that reads `AGENTS.md` and supports project skills, such as [Claude Code](https://claude.ai/code), [Cursor](https://cursor.sh), or [Codex](https://openai.com/index/introducing-codex/). ## Give the agent a focused task State the outcome, placement, data source, constraints, and expected verification. For example: ```text Add a size guide below the product description. Read it from the product metafield custom.sizing_guide. Hide the section when the metafield is empty. Run the relevant checks and verify the product page in a browser. ``` Ask the agent to propose its plan before editing when the change spans several parts of the storefront. Include exact errors when asking it to fix a failure. ## Use storefront skills Skills provide task-specific instructions and checks. In Claude Code, run a skill directly: ```bash /vercel-shop:enable-shopify-markets ``` In Cursor or Codex, describe the outcome and reference the matching skill page. Use the [`update-shop` skill](/docs/skills/update-shop) when bringing an existing storefront up to date. Source-backed storefront architecture and commerce behavior. Multi-locale and multi-currency support. ## What’s next Start with a contained storefront change, such as adding a product metafield, adjusting navigation, or changing a merchandising section. For repeated work, turn your preferred conventions and checks into a project skill so future agent changes follow the same approach. --- 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) --- title: Setup description: Set up Shopify, create a project, and run Vercel Shop locally. url: "https://shop-docs.labs.vercel.dev/docs/getting-started" docs_index: /llms.txt lastUpdated: 2026-09-07 type: guide --- > For an index of all documentation, see [/llms.txt](/llms.txt). Connect a Shopify store and run Vercel Shop locally. Use Node.js 24, the version required by the template. ## 1. Get Shopify credentials Install Shopify's **Headless** sales channel, create a storefront, and copy its **Storefront API access token**. Enable the required [Storefront API permissions](/docs/reference/storefront-api-permissions). ## 2. Create your project ```bash npx create-vercel-shop@latest my-store cd my-store ``` To deploy instead, use the Vercel flow: Deploy with Vercel The deploy flow offers the Shopify integration. Before deploying, confirm that the required [environment variables](/docs/reference/env-vars) are configured. ## 3. Add your credentials Create `.env.local` in the project root: ```bash NEXT_PUBLIC_SHOPIFY_STORE_DOMAIN="your-store.myshopify.com" NEXT_PUBLIC_SHOPIFY_STOREFRONT_ACCESS_TOKEN="shpat_1234567890abcdefghijklmnopqrstuvwxyz" ``` See [Environment Variables](/docs/reference/env-vars) for optional settings. ## 4. Run the storefront ```bash pnpm dev ``` Open [localhost:3000](http://localhost:3000) and confirm that your Shopify products appear. For local HTTPS, install [Portless](https://portless.sh) with `pnpm add -g portless`, then run `pnpm dev:portless`. Use HTTPS when testing OAuth callbacks or secure cookies. ## Next steps Configure the Shopify apps and sales channel used by the storefront. Customize the storefront with coding agents and project skills. Configure authentication, the shopping assistant, and other optional features. --- 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) --- title: Shopify Setup description: "Configure Shopify's Headless channel, Search & Discovery, and optional storefront apps." url: "https://shop-docs.labs.vercel.dev/docs/getting-started/shopify-setup" docs_index: /llms.txt lastUpdated: 2026-09-07 type: guide prerequisites: - /docs/getting-started --- > For an index of all documentation, see [/llms.txt](/llms.txt). Publish your catalog to the **Headless** sales channel first. Add the other Shopify apps only when you need their storefront features. ## Publish products to Headless Install Shopify's **Headless** sales channel and create a storefront. Enable the required [Storefront API permissions](/docs/reference/storefront-api-permissions), then publish the products and collections you want to show to **Headless**. Content published only to **Online Store** does not appear in Vercel Shop. To attribute server-side cart activity to this storefront, copy the storefront's numeric ID to `NEXT_PUBLIC_SHOPIFY_STOREFRONT_ID`. ## Configure filters and recommendations Install [Shopify Search & Discovery](https://apps.shopify.com/search-and-discovery) to configure collection and search filters. You can also assign complementary products, which appear as “Pairs Well With” on product pages. Shopify supplies related product recommendations automatically. ## Publish fixed bundles Install [Shopify Bundles](https://apps.shopify.com/shopify-bundles) if you sell fixed bundles. Publish the bundle and its component products to **Headless**; publishing only to **Online Store** is not enough. ## Next steps Configure variants, swatches, recommendations, bundles, and product SEO. See how Shopify concepts map to storefront routes and features. Keep cached storefront data in sync with Shopify Admin changes. --- 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) --- title: Environment Variables description: Required storefront credentials and optional settings for customer accounts, chat, and integrations. url: "https://shop-docs.labs.vercel.dev/docs/reference/env-vars" docs_index: /llms.txt lastUpdated: 2026-09-13 type: reference --- > For an index of all documentation, see [/llms.txt](/llms.txt). Use `.env.local` for local development and your hosting platform's environment settings for deployments. Do not commit local credentials. Only browser-safe values belong in variables prefixed with `NEXT_PUBLIC_`. ## Required These two values connect the storefront to your Shopify store. | Variable | Description | | --------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | `NEXT_PUBLIC_SHOPIFY_STORE_DOMAIN` | Store domain, such as `your-store.myshopify.com`. Find it in **Settings → Domains** in Shopify admin. | | `NEXT_PUBLIC_SHOPIFY_STOREFRONT_ACCESS_TOKEN` | Public, browser-safe Storefront API token from **Settings → Apps and sales channels → Headless**. | ## Customer authentication Customer sign-in is **disabled by default**. These values are required when you enable `auth.isEnabled` in [Shop Configuration](/docs/reference/shop-config). Follow [Authentication](/docs/anatomy/authentication) to configure Shopify and its callback URLs. | Variable | Description | | -------------------------------------------- | --------------------------------------------------------------------------------------------- | | `CUSTOMER_ACCOUNT_SESSION_SECRET` | App-generated secret for encrypting customer session cookies. Shopify does not supply it. | | `SHOPIFY_CUSTOMER_ACCOUNT_API_CLIENT_ID` | Client ID from **Sales channels → Headless → Customer Account API** in Shopify admin. | | `SHOPIFY_CUSTOMER_ACCOUNT_API_CLIENT_SECRET` | Server-only client secret issued by Shopify for the confidential Customer Account API client. | Generate `CUSTOMER_ACCOUNT_SESSION_SECRET` with `openssl rand -base64 32`. Keep the same value across all instances of a deployment. Rotating it signs out existing customers. Keep both the session secret and Shopify client secret server-only. ## Shop Agent Shop Agent is **disabled by default** and needs no AI credentials while disabled. To enable it, follow [Shop Agent setup](/docs/anatomy/agent). | Variable | When to set it | | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `AI_GATEWAY_API_KEY` | Set a server-only Gateway key when running Shop Agent without Vercel deployment identity authentication, including local development without that authentication. | | `UCP_AGENT_PROFILE_URL` | Override the public profile used for Shopify catalog search. Defaults to `/agent/ucp-profile.json` at `site.url`; local development and Vercel previews use Shopify's public example profile. | ## Optional | Variable | When to set it | | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | `DEBUG_SHOPIFY` | Set to `1` or `true` when troubleshooting Shopify API requests. Enables detailed operation and timing logs. | | `NEXT_PUBLIC_SHOPIFY_STOREFRONT_ID` | Set to the numeric ID of your Headless storefront when you need storefront-specific cart attribution. | | `SHOPIFY_API_VERSION` | Override the Storefront API version. Defaults to `unstable`; this does not select the Customer Account API version. | | `SHOPIFY_WEBHOOK_SECRET` | Set when configuring Shopify webhooks. Used to verify signatures on `POST /api/webhooks/shopify`. | ## Platform-provided values Vercel supplies `VERCEL_PROJECT_PRODUCTION_URL`, which sets the default production origin. For another host or a custom origin, set `site.url` in [Shop Configuration](/docs/reference/shop-config). `V0_CALLBACK_URL` is supplied by v0 previews to disable image optimization there. You do not need to set it for ordinary development or deployment. --- 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) --- title: Routes description: Storefront URLs, optional account and chat routes, and service endpoints. url: "https://shop-docs.labs.vercel.dev/docs/reference/routes" docs_index: /llms.txt lastUpdated: 2026-09-13 type: reference --- > For an index of all documentation, see [/llms.txt](/llms.txt). Storefront pages use the paths below without a language prefix. Customer accounts and Shop Agent are optional and disabled by default. ## Pages | Route | Description | | ------------------------------------- | --------------------------------------------------------- | | `/` | Home page | | `/products/[handle]` | Product details; option query parameters select a variant | | `/collections` | Collection index | | `/collections/[handle]` | Collection with filtering, sorting, and pagination | | `/collections/all` | All products | | `/search` | Product search results | | `/cart` | Full cart page | | `/blogs/[blogHandle]` | Shopify blog | | `/blogs/[blogHandle]/[articleHandle]` | Shopify article | | `/pages/[handle]` | Shopify page | | `/policies/[handle]` | Store policy | ## Service endpoints | Route | Description | | ---------------------------- | --------------------------------------------------- | | `GET /api/cart` | Read the current cart | | `POST /api/cart` | Create a cart or change its contents | | `GET /api/predictive-search` | Search suggestions | | `POST /api/ucp/mcp` | UCP MCP proxy | | `POST /api/webhooks/shopify` | Receive signed Shopify webhooks for catalog updates | See [Cart](/docs/anatomy/cart) for shopper behavior and [Environment Variables](/docs/reference/env-vars) for webhook configuration. ## Shop Agent These endpoints are available only when `agent.isEnabled` is `true`. Follow [Shop Agent setup](/docs/anatomy/agent) before enabling them. | Route | Description | | ----------------------------- | -------------------------------------------------------------------- | | `/eve/v1/*` | Conversation creation, messages, history, and controls | | `POST /api/agent/session` | Prepare the browser cart for chat; accepts same-origin requests only | | `GET /agent/ucp-profile.json` | Public profile for the assistant's Shopify catalog integration | Conversation endpoints are supplied by [Eve](https://eve.dev/docs). Enabling customer accounts does not make conversations private; see the [chat privacy requirements](/docs/anatomy/agent#privacy-and-usage-limits). ## Customer accounts These routes require `auth.isEnabled` to be `true` and the [customer authentication credentials](/docs/reference/env-vars#customer-authentication). Account pages require sign-in. See [Authentication](/docs/anatomy/authentication) for setup and callback URLs. | Route | Description | | ------------------------ | ---------------------------------------- | | `/account` | Redirect to `/account/profile` | | `/account/profile` | Customer profile | | `/account/addresses` | Saved addresses | | `/account/orders` | Order history | | `/account/orders/[id]` | Order details | | `GET /account/login` | Start customer sign-in | | `GET /account/authorize` | Sign-in callback | | `GET /account/refresh` | Refresh the customer session | | `POST /account/logout` | Sign out; requires a same-origin request | ## Discovery and Markdown | Route | Description | | -------------------------- | ---------------------------------------------------- | | `/robots.txt` | Crawler rules | | `/sitemap.xml` | Sitemap index | | `/sitemap/[shard]` | Sitemap entries for a content group | | `/llms.txt` | Storefront guide for AI agents | | `/md` | Home page in Markdown | | `/md/products/[handle]` | Product in Markdown | | `/md/collections/[handle]` | Collection in Markdown | | `/md/search` | Search results in Markdown | | `/.well-known/ucp` | Shopify's business profile for commerce integrations | The home, product, collection-detail, and search URLs also return Markdown when requested with `Accept: text/markdown`. See [Proxy](/docs/anatomy/proxy) when adding custom routing or integrations. ## Variant URLs Product options use one query parameter per option. The key is the option name in Shopify, and the value is the selected option value. For example, `/products/your-product?Color=Blue&Size=XS` selects the blue, extra-small variant. Names and values are matched case-insensitively, so `?color=blue&size=xs` selects the same options. Without option parameters, the page uses the product's default variant. Liquid-style links such as `/products/your-product?variant=123456789` redirect to the matching option-parameter URL. Selecting an option on the same product keeps unrelated query parameters, such as campaign tags. --- 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) --- title: Shop Configuration description: "Choose optional storefront features and set your store's identity and locale." url: "https://shop-docs.labs.vercel.dev/docs/reference/shop-config" docs_index: /llms.txt lastUpdated: 2026-09-13 type: reference --- > For an index of all documentation, see [/llms.txt](/llms.txt). Edit `lib/config/index.ts` to choose which features your storefront offers. Keep credentials in [environment variables](/docs/reference/env-vars) and manage catalog content in Shopify. Customer accounts, Shop Agent, analytics, bot protection, and WebMCP are **disabled by default**. Enable only the features you intend to use and complete their setup before deploying. ## Settings | Setting | Default | Behavior | | ------------------------------------- | -------------------- | -------------------------------------------------------------------------------- | | `agent.isEnabled` | `false` | Enables Shop Agent for product discovery, store questions, and cart updates. | | `analytics.vercel.isEnabled` | `false` | Enables Vercel Web Analytics. | | `analytics.speedInsights.isEnabled` | `false` | Enables Vercel Speed Insights. | | `analytics.shopify.isEnabled` | `false` | Sends browsing and cart events to Shopify, subject to consent. | | `analytics.shopify.consentMode` | `default-banner` | Chooses how shoppers give analytics consent; see below. | | `auth.isEnabled` | `false` | Enables customer sign-in and account pages. | | `botid.isEnabled` | `false` | Enables Vercel BotID checks for Shop Agent requests. | | `botid.checkLevel` | `basic` | Chooses `basic` or `deepAnalysis` bot detection. | | `browserAgents.webmcp.isEnabled` | `false` | Registers Shopify catalog and cart tools with WebMCP in supported browsers. | | `localization.country` | `"US"` | Sets the country used for Shopify pricing and availability. | | `localization.language` | `"EN"` | Requests Shopify content in this language. | | `localization.locale` | `"en-US"` | Sets display formatting; does not translate interface text or select a currency. | | `pdp.bundles.isEnabled` | `true` | Shows bundle relationships when Shopify provides them. | | `pdp.buyWithShop.isEnabled` | `true` | Shows Buy with Shop. | | `pdp.complementaryProducts.isEnabled` | `true` | Shows complementary products when Shopify provides them. | | `pdp.quantityPicker.isEnabled` | `true` | Shows the product quantity picker. | | `pdp.relatedProducts.isEnabled` | `true` | Shows related products when Shopify provides them. | | `search.isEnabled` | `true` | Shows the header search button and predictive search dialog. | | `site.name` | `"Vercel Shop"` | Sets the storefront name. | | `site.url` | Deployment-dependent | Sets the public origin used for canonical URLs, metadata, and discovery links. | ## Before enabling optional features **Shop Agent** requires AI Gateway access in addition to the storefront's Shopify connection. Customer sign-in is not required. Follow [Shop Agent setup](/docs/anatomy/agent), including its privacy and spending safeguards, before enabling public traffic. **Customer accounts** require a Shopify client ID, Shopify client secret, and a separate app-generated session secret. Follow [Authentication](/docs/anatomy/authentication) to configure those values and register callback URLs before enabling `auth.isEnabled`. **Bot protection** can be enabled separately for Shop Agent on Vercel. Review [BotID pricing](https://vercel.com/docs/botid#pricing) before choosing `deepAnalysis`. It does not make chat history private or cap AI spending. ## Store identity and locale On Vercel, `site.url` uses the project's production domain. Elsewhere it defaults to `http://localhost:3000`; set it to your public storefront origin before deploying. Country and language control the Shopify context. The formatting locale controls how values are displayed. Changing these settings does not translate storefront interface text, and currency comes from Shopify's responses. See [Shopify Markets](/docs/skills/enable-shopify-markets) or [i18n](/docs/skills/enable-i18n) when adding localized storefronts. ## Shopify consent modes These modes apply when Shopify analytics is enabled. | Value | Behavior | | ---------------- | -------------------------------------------------------------------------------------------- | | `default-banner` | Uses Shopify's hosted privacy banner where consent is required. | | `custom-banner` | Requires you to provide a consent interface connected to Shopify's Customer Privacy API. | | `no-banner` | Shows no consent interface. Where consent is required, analytics events cannot be delivered. | Only expose the public Storefront API token to the browser. Never use a private token for Shopify analytics or consent requests. ## Related configuration Manage navigation and footer menus with [Shopify Menus](/docs/skills/enable-shopify-menus). [WebMCP](/docs/anatomy/webmcp) is independent of Shopify analytics. Enabling one does not enable the other. --- 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) --- title: Storefront API Permissions description: Shopify Storefront API scopes for the default storefront and custom data. url: "https://shop-docs.labs.vercel.dev/docs/reference/storefront-api-permissions" docs_index: /llms.txt lastUpdated: 2026-09-07 type: reference prerequisites: - /docs/getting-started --- > For an index of all documentation, see [/llms.txt](/llms.txt). After [Getting Started](/docs/getting-started), open **Settings → Apps and sales channels → Headless → your storefront** in Shopify admin and grant these Storefront API permissions to the token. ## Required | Scope | Enables | | --------------------------------------- | -------------------------------------------------- | | `unauthenticated_read_product_listings` | Products, collections, search, and recommendations | | `unauthenticated_read_product_tags` | Product tags requested by the storefront | | `unauthenticated_write_checkouts` | Cart operations and checkout | | `unauthenticated_read_content` | Pages, blogs, and articles | ## Optional Grant optional scopes only when your storefront queries the related data. | Scope | Enables | | ---------------------------------------- | ------------------------------------------------------------------------------------------------------- | | `unauthenticated_read_product_inventory` | Inventory quantities, such as `quantityAvailable`; not required for the default availability indicators | | `unauthenticated_read_metaobjects` | Custom content stored in metaobjects | Customer sign-in uses separate Customer Account API permissions. See [Authentication](/docs/anatomy/authentication) for account setup and [Shopify's scope reference](https://shopify.dev/docs/api/usage/access-scopes) for additional permissions. See [Environment Variables](/docs/reference/env-vars) for token configuration and [Storefront API](/docs/reference/storefront-api) for query validation and runtime behavior. --- 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) --- title: Storefront API description: "How the template calls Shopify's Storefront GraphQL API - the fetch client, query patterns, caching, and error handling." url: "https://shop-docs.labs.vercel.dev/docs/reference/storefront-api" docs_index: /llms.txt lastUpdated: 2026-09-14 type: reference prerequisites: - /docs/getting-started --- > For an index of all documentation, see [/llms.txt](/llms.txt). The template uses the framework-agnostic [Shopify Hydrogen](https://www.npmjs.com/package/@shopify/hydrogen) preview SDK for Storefront GraphQL API queries and mutations. It runs on Next.js, not the Hydrogen React Router framework. Next.js owns page routing, rendering, and public-data caching; Hydrogen supplies Shopify API clients and commerce handlers. Configure the store domain, public token, and API version with the variables in [Environment Variables](/docs/reference/env-vars). Grant the scopes in [Storefront API Permissions](/docs/reference/storefront-api-permissions). The Customer Account API uses a separate endpoint and schema. Enabling authentication requires `SHOPIFY_CUSTOMER_ACCOUNT_API_CLIENT_ID`, `SHOPIFY_CUSTOMER_ACCOUNT_API_CLIENT_SECRET`, and a separate app-generated `CUSTOMER_ACCOUNT_SESSION_SECRET` for encrypted session cookies. Keep both secrets server-only. Its documents use `gql` from `@shopify/hydrogen/customer-account` and are validated separately from Storefront documents. ## Write and validate operations Define each operation with Hydrogen's `gql()` tag and pass dynamic values as GraphQL variables. Do not interpolate runtime values or conditional fields into the document. Compose shared selections by passing fragment documents as the second argument. Result and variable types are inferred from the document, so the request wrapper returns typed data without a hand-written response type. Include Shopify's `@inContext` directive when localized pricing or content depends on country and language. The wrapper defaults `$country` and `$language` to `shopConfig.localization.country` and `shopConfig.localization.language`. The separate `shopConfig.localization.locale` controls display formatting; it does not select a market or currency. Currency comes from Shopify. Omit the operation's `locale` option to use the deployment settings. For an explicit commerce context, pass a `{ country, language }` object, not a formatting locale string. Keep that object in cached operation arguments when results vary by market or language: ```ts import { gql } from "@shopify/hydrogen"; const GET_PRODUCT_QUERY = gql(`#graphql query getProduct( $handle: String! $country: CountryCode $language: LanguageCode ) @inContext(country: $country, language: $language) { productByHandle(handle: $handle) { id title } } `); const response = await storefront.request(GET_PRODUCT_QUERY, { locale: { country: "US", language: "EN" }, variables: { handle }, }); ``` Validate current field names, arguments, and types with Shopify AI Toolkit. Then use the [`shopify-graphql-reference` skill](/docs/skills/shopify-graphql-reference) for template integration conventions. The skill is not a schema source. ## Caching Public-data operations use Next.js Cache Components and cache tags; the Hydrogen client does not replace that cache layer. Choose caching by data sensitivity and behavior: | Data or operation | Cache contract | | ---------------------------------------------------------- | ------------------------------------------------------------- | | Public product, collection, menu, or content data | Cache and invalidate when Shopify changes | | Public results that vary by filters, search, or pagination | Share only when the cache key includes every varying input | | Cart, session, authorization, or customer data | Keep request-scoped or private; never place in a public cache | | Mutations | Do not cache | Configure `POST /api/webhooks/shopify` as described in [Webhooks](/docs/anatomy/webhooks) to refresh cached products and collections after edits. The handler supports product, collection, and metaobject topics; other content needs its own invalidation strategy or cache expiry. ## Mutations Storefront cart forms submit to Hydrogen's `POST /api/cart` handler through the Next.js proxy, not to cart Server Actions. Mutations are uncached and return the updated cart for Hydrogen's client store to reconcile. Cart updates do not invalidate the public catalog cache. The optional shopping assistant uses the same handlers on the server. After a successful tool result, the browser refreshes the shared cart store. See [Cart](/docs/anatomy/cart) for shopper behavior and limits. Never cache cart IDs, customer data, session data, or authenticated responses in a shared public cache. ## Errors and missing resources Storefront requests throw on transport failures and timeouts. The request wrapper returns GraphQL errors alongside data; read operations check the result with `assertStorefrontOk`. This check throws when no data is returned and logs a warning when errors accompany partial data. A missing resource is not an API failure. Read operations return `undefined`, `null`, or an empty list when the requested resource does not exist. Set `DEBUG_SHOPIFY=true` to include structured Storefront and Customer Account API operation timings in server logs. Warnings and errors remain enabled when debug logging is off. --- 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) --- title: Troubleshooting description: Solutions to common setup and runtime issues. url: "https://shop-docs.labs.vercel.dev/docs/reference/troubleshooting" docs_index: /llms.txt lastUpdated: 2026-09-14 type: troubleshooting --- > For an index of all documentation, see [/llms.txt](/llms.txt). ## Products do not appear **Symptom:** Product pages or listings are empty. **Check:** In Shopify admin, confirm the Storefront token has the scopes in [Storefront API Permissions](/docs/reference/storefront-api-permissions). Confirm each product is active and published to the **Headless** sales channel. **Fix:** Grant the missing scopes and publish the products to Headless. Publishing to **Online Store** alone is not enough. **Expected result:** Published products appear in listings and product routes resolve. ## A bundle returns 404 **Symptom:** A bundle is active in Shopify admin but its storefront route returns `404`. **Check:** Open the bundle product's **Publishing** settings. Confirm the bundle and its component products are published to the **Headless** sales channel. **Fix:** Publish the bundle and its component products to Headless. If the route still returns `404`, confirm that a product webhook for the bundle reaches the storefront to invalidate the cached response. **Expected result:** The bundle route loads and its component relationships appear. ## The cart does not persist **Symptom:** The cart becomes empty after navigation or reload. **Check:** In browser developer tools, open **Application → Cookies** and confirm the `cart` cookie exists for the current domain. It should have a 14-day expiry. **Fix:** Use one consistent storefront domain and remove any deployment or proxy setting that rewrites the cookie domain. **Expected result:** The cart survives navigation and reloads on the same domain. The cookie has a 14-day lifetime, but it does not guarantee that Shopify will retain the cart or that the browser will keep the cookie. ## Variant selection does not update the product **Symptom:** Selecting an option changes the URL but not the price or purchase controls. **Check:** Confirm the URL contains one query parameter per option, such as `?Color=Blue&Size=XS`. Option names and values are matched case-insensitively. Confirm the selected combination exists in Shopify. **Fix:** Correct links to preserve all selected option parameters. If a valid combination still fails, validate the product and variant queries against the Storefront API schema. **Expected result:** The URL, selected variant, price, availability, and purchase controls update together. ## Images do not load **Symptom:** Shopify product images are broken or rejected by Next.js Image. **Check:** Confirm `next.config.ts` allows `cdn.shopify.com` in `images.remotePatterns`. **Fix:** Add the Shopify CDN hostname: ```ts images: { remotePatterns: [{ hostname: "cdn.shopify.com" }], }, ``` **Expected result:** Shopify CDN images render through Next.js Image. ## A Storefront request fails with GraphQL errors **Symptom:** `assertStorefrontOk()` throws, or the response reports an invalid GraphQL field, argument, type, or enum value. **Check:** Validate the operation against the live Storefront API schema for the configured `SHOPIFY_API_VERSION` using Shopify AI Toolkit; typecheck does not catch invalid fields. **Fix:** Correct the operation and load the affected route again. If Shopify AI Toolkit is unavailable, install the project plugin: ```bash npx plugins add Shopify/shopify-ai-toolkit --scope project --yes ``` Use the [`shopify-graphql-reference` skill](/docs/skills/shopify-graphql-reference) only for template integration conventions. **Expected result:** The route renders and the Storefront response carries no `errors`. ## Shopify changes do not appear **Symptom:** Updated products or collections still show old content. **Check:** Confirm Shopify webhooks are configured and signed with `SHOPIFY_WEBHOOK_SECRET`. **Fix:** Point the required Shopify webhooks to `POST /api/webhooks/shopify`. Follow [Webhooks](/docs/anatomy/webhooks) for setup. After a product or collection edit, check that Shopify reports a successful delivery and that the endpoint returns a nonempty `tagsInvalidated` list. **Expected result:** Shopify changes invalidate the affected cached content and appear without a redeploy. ## Locale or currency does not change **Symptom:** The storefront keeps one language or currency after a regional selection. **Check:** The default serves one deployment using `shopConfig.localization` in `lib/config/index.ts`. Storefront copy, display formatting, and Shopify commerce context are separate. A formatting locale does not translate labels or convert prices. **Fix:** Edit [storefront copy](/docs/anatomy/i18n) for a single-language deployment, or use [Enable i18n](/docs/skills/enable-i18n) for translated UI and locale URLs. For regional commerce, run [`/vercel-shop:enable-shopify-markets`](/docs/skills/enable-shopify-markets) and choose locale-prefixed, cookie-based, or per-domain routing. **Expected result:** Copy changes affect labels. Markets changes send the selected commerce context to Shopify; currency comes from Shopify's response, not a storefront currency map. ## A coding agent cannot find project context **Symptom:** A coding agent misses project commands or shop-specific guidance. **Check:** Confirm your agent reads the project's `AGENTS.md` and recognizes the installed Vercel Shop, Vercel, and Shopify plugins. Plugin support and configuration depend on the agent. **Fix:** From the project root, run: ```bash npx create-vercel-shop@latest --no-template ``` If needed, install the plugins individually: ```bash npx plugins add vercel/shop --scope project --yes npx plugins add vercel/vercel-plugin --scope project --yes npx plugins add Shopify/shopify-ai-toolkit --scope project --yes ``` The `--no-template` command installs plugins; it does not restore a missing `AGENTS.md`. Restore that file from your project's version control if it was removed. **Expected result:** Your agent lists the installed plugins and can read the project guidance. --- 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) --- title: Shopify Integration description: How the template maps to Shopify concepts - menus, products, collections, and cache invalidation via webhooks. url: "https://shop-docs.labs.vercel.dev/docs/shopify" docs_index: /llms.txt lastUpdated: 2026-09-07 type: reference prerequisites: - /docs/getting-started --- > For an index of all documentation, see [/llms.txt](/llms.txt). Use this page to find where Shopify content appears in the storefront. For credentials and permissions, see [Getting Started](/docs/getting-started) and [Storefront API Permissions](/docs/reference/storefront-api-permissions). | Shopify content | Storefront location | Setup or behavior | | ------------------ | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | Products | `/products/[handle]` | [Product setup](/docs/shopify/pdp) and [PDP anatomy](/docs/anatomy/pages/pdp) | | Collections | `/collections/[handle]` | [PLP anatomy](/docs/anatomy/pages/plp) | | Pages | `/pages/[handle]` | [Content pages](/docs/anatomy/pages/content) | | Blogs and articles | `/blogs/[blogHandle]` and `/blogs/[blogHandle]/[articleHandle]` | [Content pages](/docs/anatomy/pages/content) | | Policies | `/policies/[handle]` | [Footer](/docs/anatomy/footer) | | Search | `/search` | [PLP and search anatomy](/docs/anatomy/pages/plp) | | Cart | `/cart` and cart overlay | [Cart](/docs/anatomy/cart) | | Menus | Navigation and footer | [Navigation](/docs/anatomy/navigation) and [Enable Shopify menus](/docs/skills/enable-shopify-menus) | Navigation uses the template's configured links by default. To manage navigation and footer links in Shopify Admin, follow [Enable Shopify menus](/docs/skills/enable-shopify-menus). Configure [Shopify webhooks](/docs/anatomy/webhooks) so product and collection edits appear promptly. Without webhooks, cached content remains until its cache lifetime expires. For Storefront API behavior, see [Storefront API](/docs/reference/storefront-api). --- 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) --- title: Product Setup description: Shopify product configuration for the Product Detail Page - variants, swatches, recommendations, bundles, and SEO. url: "https://shop-docs.labs.vercel.dev/docs/shopify/pdp" docs_index: /llms.txt lastUpdated: 2026-09-07 type: reference prerequisites: - /docs/anatomy/pages/pdp --- > For an index of all documentation, see [/llms.txt](/llms.txt). Configure a Shopify product so shoppers can find it, choose a variant, and add it to the cart. For storefront behavior, see [Anatomy → PDP](/docs/anatomy/pages/pdp). ## Publish the product Add a title, description, featured image, and at least one variant. Assign the product to a collection if it should appear on a collection page, then publish it to the **Headless** sales channel. Open its storefront URL and confirm that the product loads and an available variant can be added to the cart. ## Add option swatches Configure color or image swatches for the product's option values in Shopify Admin. The storefront displays those swatches when available. Color options can also use variant images; other options use text buttons. A single-value option is shown as a label rather than a picker. ## Configure recommendations Shopify provides related products automatically. To show complementary products as “Pairs Well With,” install [Shopify Search & Discovery](https://apps.shopify.com/search-and-discovery) and assign recommendations under **Product recommendations**. The section stays hidden when no complementary products are assigned. ## Publish a fixed bundle Create the bundle with [Shopify Bundles](https://apps.shopify.com/shopify-bundles), then publish it to **Headless**. A bundle available only on **Online Store** does not appear in Vercel Shop. Publish the component products to Headless as well. If the bundle still does not appear, see [Troubleshooting → A bundle returns 404](/docs/reference/troubleshooting#a-bundle-returns-404). ## Set search and sharing details Set the product's search engine title and description in Shopify Admin when the defaults are not suitable. Otherwise, the storefront uses the product title and description. --- 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) --- title: Build with Vercel Shop description: Build or adapt Shopify storefronts with source-backed Vercel Shop patterns. url: "https://shop-docs.labs.vercel.dev/docs/skills/build-shop" docs_index: /llms.txt lastUpdated: 2026-09-15 type: guide --- > For an index of all documentation, see [/llms.txt](/llms.txt). ## How to use ```bash /vercel-shop:build-shop ``` Use this skill to build or adapt home, collection, search, product, cart, and account pages while preserving storefront behavior.
# Build with Vercel Shop Build the shop around commerce truth first: what product or collection is being shown, what the customer has selected, what can be bought now, what price is authoritative, and what state belongs in the URL, Shopify, the server cache, or the browser. Use Vercel Shop's template as the reference implementation, but adapt the behavior to the current storefront instead of copying files blindly. ## Ground the work in source 1. Read the project's `AGENTS.md`, the target route, its view contract, and every operation it calls. 2. If the Vercel Shop template source is available, inspect it before relying on this prose: - Template rules: `apps/template/AGENTS.md` - Route/layout shell: `apps/template/app/layout.tsx`, `apps/template/app/page.tsx` - Shopify boundary: `apps/template/lib/shopify/storefront/server.ts`, `apps/template/lib/shopify/operations/`, `apps/template/lib/shopify/transforms/`, `apps/template/lib/product/types.ts`, `apps/template/lib/customer/types.ts` - Next.js cache boundary: `apps/template/lib//server.ts` cached `get*` wrappers around the uncached `fetch*` operations - Shared UI layout primitives: `apps/template/components/ui/container.tsx`, `apps/template/components/ui/page.tsx`, `apps/template/components/ui/sections.tsx` - Public source fallback: [apps/template source](https://github.com/vercel/shop/tree/main/apps/template) 3. Use the docs to orient before editing unfamiliar areas: - [Architecture docs](https://vercel.shop/docs/anatomy) - [Route reference](https://vercel.shop/docs/reference/routes) - [Shopify integration docs](https://vercel.shop/docs/shopify) - [API boundary docs](https://vercel.shop/docs/reference/storefront-api) 4. Read the local Next.js documentation under `node_modules/next/dist/docs/` for any API being changed. This template may use newer Cache Components and prefetch behavior than model knowledge. 5. Preserve existing cache directives, promises, invalidation tags, auth gates, redirects, metadata, and `notFound()` behavior unless the task explicitly changes the domain behavior. ## Hydrogen ownership The template uses the framework-agnostic Hydrogen preview SDK, not Hydrogen's React Router application framework. Next.js owns routing, rendering, public-data caching, and invalidation. Hydrogen owns commerce state and protocols; the template supplies presentation and framework adapters. Use Hydrogen's cart provider/forms/handlers rather than rebuilding cart state or hydration. Cart types are handler-derived; catalog/account presentation uses domain transforms. Read the installed SDK guidance and verify adapter behavior before changing these boundaries. ## Organize code by domain and execution context Organize `lib/` by domain, then use only the context files that domain needs: - `index.ts` contains universal implementation safe for server and client imports; it is never a re-export barrel. - `server.ts` contains server-side implementation; keep it out of client import graphs. - `client.ts` is a `"use client"` boundary for browser interaction, not an HTTP transport wrapper. - `action.ts` is a `"use server"` entry point whose exports use a verb plus `Action` suffix. - `types.ts` owns named shared contracts; consumers import types directly rather than through `server.ts` or `action.ts`. Subdivide large domains with the same context filenames. Put Shopify transports in their API domain's `server.ts` and pure transforms in `index.ts`, even when all current callers run on the server. Do not add descriptive sibling files, flat root implementation modules, empty entry points, forwarding exports, or barrels. Keep storefront models in their owning domain's `types.ts`, such as `lib/product/types.ts`, `lib/collections/types.ts`, and `lib/customer/types.ts`. Shared use does not change ownership: primitives live in `lib/money/types.ts`, `lib/media/types.ts`, and `lib/pagination/types.ts`. Types-only domains need no `index.ts` or re-export barrel. Keep SDK-specific contracts under `lib/shopify/` and handler-derived cart contracts in `lib/cart/types.ts`. Component props stay with their component; small private implementation types may stay local. Generated artifacts keep generator-owned paths and names. ## Copy and deployment defaults The default storefront uses inline component copy and reusable content functions in `lib/content/index.ts`. Keep copy server-first, pass primitive labels to UI primitives and client leaves, and keep interactive copy in its consuming leaf and import shared content functions only when needed. Do not add a custom `t()` parser, a full browser catalog, or next-intl for a single deployment. `shopConfig.localization` explicitly sets `{ country: "US", language: "EN", locale: "en-US" }`; country/language configure commerce requests and locale configures formatting. Currency comes from Shopify. Clean URLs and one deployment are the default; `lib/i18n/` and a Server Component locale resolver are absent. Operation locale/cache inputs may still be intentional. Preserve existing next-intl, catalogs, localized routes, and custom commerce behavior in upgraded installations. Use `enable-i18n` for copy/routing or `enable-shopify-markets` for regional commerce rather than coupling the two implicitly. ## Shop Agent boundaries Shop Agent, customer authentication, and BotID are disabled by default. Preserve the installation's feature settings; a storefront redesign or localization change must not enable them implicitly. For assistant changes, read the installed Eve docs starting at `node_modules/eve/docs/README.md`, then only the guide relevant to the task. Preserve Next.js deployment through `withEve` and the conditional plugin list passed to `withShopConfig` in `next.config.ts`. Eve owns `/eve/v1/*`. Next.js prepares the browser cart through `/api/agent/session`; do not add another chat route or internal commerce HTTP bridge. Tool schemas and execution belong in `agent/tools/`, shared execution helpers in `agent/lib/`, and browser state, presentation helpers, and shared result types in `lib/agent/`. Keep Next.js request/cache APIs out of Eve's runtime imports. Use shared uncached catalog operations and Hydrogen cart handlers directly, with cart identity bound from the browser cookie rather than model arguments. Preserve confirmed-mutation signals and Hydrogen reconciliation; restored messages must not replay cart writes or reopen the drawer. Do not claim exactly-once writes, conversation ownership, or server-history deletion on Clear. For conversation changes, check multiple search turns, visible results, and cumulative usage. For session controls, check restoration, Stop/Clear recovery, and failures. Mitigate abuse and cost with BotID, rate limits, and Gateway spending controls rather than per-session token caps. Distinguish browser/live-store evidence from mocks and build checks. ## Route the work Read `references/rendering-architecture.md` for every route. Then read only the route references that apply: - Commerce behavior and end-to-end flows: `references/commerce-flows.md` - Home and marketing routes: `references/home.md` - Collection and search routes: `references/plp-search.md` - Product routes: `references/pdp.md` - Cart and authenticated account routes: `references/cart-account.md` - Cart provider, bootstrap, optimistic state, and mutations: `references/cart-provider.md` ## Model the route Write down the route as five layers before editing, using commerce nouns instead of generic component names: 1. **Route orchestration** — resolve handles, locale, selected options, filters, pagination, redirects, metadata, auth, and real 404s. 2. **Data operation** — fetch Shopify data, transform provider types into shop domain types, and own cache scope, tags, and invalidation names. 3. **Server composition** — render the stable catalog shell first and place independent sections like recommendations, facets, reviews, and account/cart details behind granular boundaries. 4. **Client island** — own only selection, optimistic intent, browser APIs, effects, and event handlers: variant pickers, galleries, filter controls, carts, and forms. 5. **Mutation boundary** — use server actions for app-owned mutations and Hydrogen's proxy handlers for browser cart mutations. Return canonical Shopify state and warnings; invalidate public domain caches only when applicable. Let Hydrogen reconcile cart state without a parallel optimistic reducer. For each layer's full ownership boundary, see the responsibility table in `references/rendering-architecture.md`. For every dependency, classify it as cacheable shell content, request-time shared content, request-time personalized content, or client-only state. Draw an edge only when one result genuinely requires another. Start all other work concurrently. ## Storefront gotchas - Product selection must round-trip through direct visits, links, refreshes, and client navigation, then drive media, price, availability, add-to-cart payloads, and canonical links. - Collection/search URLs are the source of truth for browsing. Empty results, unavailable facets, and back/forward navigation are not optional states. - Cart UI must keep confirmed Shopify state separate from pending optimistic intent so concurrent mutations, bootstrap, errors, and warnings cannot double-apply or disappear. - Customer, account, cart identity, and authorization state must never leak into shared product, collection, menu, page, or recommendation caches. - Missing images, deleted products, sold-out variants, empty collections, partial Shopify failures, and disabled auth are normal storefront cases. Represent them deliberately. ## Keep the Shopify boundary explicit Use the installed Shopify AI Toolkit for Shopify API documentation, schema facts, operation design, and validation. Invoke its API-specific skill before adding or changing Storefront or Customer Account GraphQL. For metafields or metaobjects, use its custom-data skill first. Use `/vercel-shop:shopify-graphql-reference` only after Shopify validation to apply Vercel Shop conventions: operation placement, domain transforms, cache role, locale flow, invalidation, and route integration. Never treat this architecture skill as a substitute for authoritative Shopify validation. ## Prevent blocking 1. Keep route identity, stable headings, primary media, selected price/availability, and likely LCP content in the earliest shell the data contract permits. 2. Resolve route identity early only when it is required for correctness or shell coherence. 3. Pass request-dependent promises downward unawaited. Resolve them in the smallest component that needs them and place Suspense there. 4. Use sibling boundaries for independent work. Do not put the whole page behind the slowest Shopify request. 5. Give every visible fallback the same outer geometry as its resolved content. 6. Keep components server-rendered by default. Do not move reads into client effects or internal HTTP endpoints. 7. Keep cache policy in the data layer and personalized data out of shared caches. 8. Treat prefetching as a traffic-versus-latency decision, not a default fix for blocking architecture. ## Use a browser feedback loop For visible storefront changes, close the loop in a real browser before calling the work done. Use the agent's built-in browser when available; otherwise use the standalone `agent-browser` CLI. 1. Start the local storefront and open each affected route: `agent-browser open http://localhost:3000/...`. 2. Capture the current state: `agent-browser wait --load networkidle`, `agent-browser snapshot`, and `agent-browser screenshot --full`. 3. Exercise the commerce interaction through the UI: variant selection, filtering, pagination, add/update/remove cart, auth redirects, or the changed control. 4. Re-snapshot after every navigation or DOM change before reusing element refs. 5. Repeat on mobile and desktop viewports when layout, media, overlays, filters, cart, or primary actions changed. 6. Iterate on the implementation until the browser outcome matches the intended commerce behavior. If `agent-browser` is unavailable, say so and report the fallback checks used. ## Verify the architecture Run the static hotspot scan from the skill directory: ```bash node scripts/audit-storefront.mjs ``` Treat its output as review prompts, not measurements. Then: 1. Run targeted lint, typecheck, tests, and affected flows available in the current environment. 2. Test direct visits, client navigations, back/forward navigation, and URL round-trips for the routes changed. 3. Verify that non-critical Shopify work does not delay the shell, primary media, selected price/availability, or primary interaction. 4. Run every affected flow in `references/commerce-flows.md`, including failure, empty, sold-out, and missing-media states. 5. Inspect failed requests, layout shifts, LCP discovery, hydration, and interaction behavior when relevant. 6. Require a production build only when build, prerendering, caching, bundling, deployment behavior, or release readiness is in scope. 7. Use bundle analysis or deployed field data only for an explicit performance investigation when those tools and data are available. Do not request them as routine completion work or claim measured improvement from code inspection. Report the final layer boundaries, blocking dependencies, cache ownership, and remaining risks. --- 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) --- title: Analytics description: Add Vercel Analytics, Vercel Speed Insights, and Google Tag Manager to the storefront. url: "https://shop-docs.labs.vercel.dev/docs/skills/enable-analytics" docs_index: /llms.txt lastUpdated: 2026-09-13 type: guide --- > For an index of all documentation, see [/llms.txt](/llms.txt). ## How to use ```bash /vercel-shop:enable-analytics ```
# Enable Analytics The current storefront includes support for Vercel Web Analytics and Vercel Speed Insights, with each integration disabled by default in `lib/config/index.ts`. This skill enables or adds those integrations and can also add Google Tag Manager using the recommended integration. ## Before you start Ask the user two questions in order: ### 1. Do you need to add or change Vercel Analytics and/or Vercel Speed Insights? - **Enable both** — page views, custom events, and Core Web Vitals - **Analytics only** — page view and custom event tracking via `@vercel/analytics` - **Speed Insights only** — Core Web Vitals monitoring via `@vercel/speed-insights` - **Neither** — keep both integrations disabled ### 2. Do you want Google Tag Manager? If yes, ask for the GTM container ID (e.g. `GTM-XXXXXX`). This will be stored in the `NEXT_PUBLIC_GTM_ID` environment variable. Wait for the user to answer both questions before proceeding. *** ## Part A: Vercel Analytics and Speed Insights If the storefront has `analytics` configuration in `lib/config/index.ts`, enable only the selected integrations. If the user selected neither, keep both integration gates disabled and skip the remaining steps in this section. ```ts analytics: { shopify: { consentMode: "default-banner", isEnabled: false }, speedInsights: { isEnabled: false }, vercel: { isEnabled: false }, }, ``` The `shopify` gate is separate: it controls Shopify storefront analytics, which the storefront already ships. Leave it alone unless the user asked about Shopify analytics, and see Part D. ### A1. Install dependencies For older storefronts without the integrations, install only the packages the user selected: ```bash # Both pnpm add @vercel/analytics @vercel/speed-insights # Analytics only pnpm add @vercel/analytics # Speed Insights only pnpm add @vercel/speed-insights ``` For older storefronts, create or update the root analytics component described below. Each library handles its own client-side behavior internally. *** ## Part B: Google Tag Manager Skip this section if the user did not want GTM. ### B1. Install dependency ```bash pnpm add @next/third-parties ``` ### B2. Add environment variable Add to `.env.example`: ``` # Google Tag Manager (optional) NEXT_PUBLIC_GTM_ID="GTM-XXXXXX" ``` Set the actual value in `.env.local` or in the Vercel dashboard under Environment Variables. ### B3. Add GTM to `components/analytics/index.tsx` Import `GoogleTagManager` from `@next/third-parties/google`. Read `NEXT_PUBLIC_GTM_ID` in the analytics component and render `` only when the value exists. If the storefront extends `lib/config/index.ts` with a GTM integration gate, apply that gate inside the same component. *** ## Part C: Root analytics integration ### C1. Update `components/analytics/index.tsx` Extend the existing root analytics component. Do not create a sibling `components/analytics.tsx`, which would shadow the directory import. Preserve `ShopifyScriptsTracker`, its shop data, and the existing consent integration while adding the selected providers: ```tsx import { GoogleTagManager } from "@next/third-parties/google"; import { Analytics } from "@vercel/analytics/next"; import { SpeedInsights } from "@vercel/speed-insights/next"; import { shopConfig } from "@/lib/config"; import { getShopAnalytics } from "@/lib/analytics/server"; import { ShopifyScriptsTracker } from "./shopify-client"; export async function AnalyticsComponents() { const gtmId = process.env.NEXT_PUBLIC_GTM_ID; return ( <> {shopConfig.analytics.vercel.isEnabled ? : null} {shopConfig.analytics.speedInsights.isEnabled ? : null} {gtmId ? : null} ); } ``` Remove imports for integrations the storefront does not support. ### C2. Update `app/layout.tsx` Render the root analytics component near the end of ``. The default has inline component copy, not a translation provider; in an already localized installation, preserve its scoped translation-provider boundaries: ```tsx import { AnalyticsComponents } from "@/components/analytics"; ``` ```tsx {/* ... existing layout content and scoped providers ... */} ``` Do not add next-intl or a root message catalog for analytics. In a customized localized storefront, preserve any required commerce locale prop and existing scoped providers; do not pass the complete catalog to a root `NextIntlClientProvider`. The root component remains mounted as the extension point for current and future analytics providers. Provider gates stay inside it so disabled integrations are not mounted. ## Part D: Shopify storefront analytics Only make changes here if the user asked about Shopify analytics. The storefront sends page, product, collection, search, cart-view, and confirmed cart-change events through Hydrogen's analytics bus. It is disabled by default and requires no credentials beyond the Storefront API variables the storefront already needs. To turn Shopify's built-in analytics destination on, set `analytics.shopify.isEnabled` to `true` in `lib/config/index.ts`. Consent mode is set by `analytics.shopify.consentMode` in `lib/config/index.ts` and defaults to `default-banner`, which renders Shopify's hosted privacy banner for visitors in regions that require consent. Use `custom-banner` when the storefront supplies its own consent UI. Do not ship `no-banner` in production unless consent is handled elsewhere, because visitors in those regions can never grant consent and their events are dropped. Third-party analytics can subscribe through the same destination API, so consent gating and buffered replay remain centralized. Register destinations with `addAnalyticsDestination()` from `lib/analytics/client.ts`; do not publish cart-change events manually. ## Guardrails - Keep root analytics providers and their gates in `components/analytics/index.tsx`; preserve the existing Shopify scripts and consent integration. - Always mount `` from the root layout, even when every provider is disabled. - The GTM container ID must come from `NEXT_PUBLIC_GTM_ID`, never hardcoded. The provider renders nothing if the env var is missing. - Use `@next/third-parties/google` for GTM, not a manual `