# 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: `AGENTS.md` - Route/layout shell: `app/layout.tsx`, `app/page.tsx` - Shopify boundary: `lib/shopify/storefront/server.ts`, `lib/shopify/operations/`, `lib/shopify/transforms/`, `lib/product/types.ts`, `lib/customer/types.ts` - Next.js cache boundary: `lib//server.ts` cached `get*` wrappers around the uncached `fetch*` operations - Shared UI layout primitives: `components/ui/container.tsx`, `components/ui/page.tsx`, `components/ui/sections.tsx` - Public source fallback: [template source](https://github.com/vercel/shop) 3. Use the docs to orient before editing unfamiliar areas: - [Documentation index](https://vercel.shop/llms.txt) - [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. - `request.ts` contains code that takes the `Request` or `Headers` explicitly, such as Hydrogen handlers and session cookies; the root `proxy.ts` and Route Handlers import it. It never imports `next/cache`, `next/headers`, `next/navigation`, or `react`, which load the App Router runtime into the proxy; `server.ts` may import it. - `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 `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://vercel.shop/docs/skills/enable-analytics" docs_index: /llms.txt lastUpdated: 2026-10-14 type: guide --- > For an index of all documentation, see [/llms.txt](/llms.txt). ## How to use Ask your agent to use the `enable-analytics` skill, or run it as a slash command in Claude Code: ```text /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: { consent: { isEnabled: false, mode: "default-banner" }, isEnabled: false, }, speedInsights: { isEnabled: false }, vercel: { isEnabled: false }, }, ``` The `shopify` gate is separate: it controls Shopify storefront analytics and its consent integration. Standalone consent can be enabled separately through `shopify.consent.isEnabled`. Leave these settings alone unless the user asked about Shopify analytics or consent, 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 this row to the `# Optional` block of `.env.example`, keeping it alphabetical: ```bash # NEXT_PUBLIC_GTM_ID="GTM-XXXXXX" # Set to load Google Tag Manager; leave unset to skip it. ``` Add `NEXT_PUBLIC_GTM_ID` to `turbo.json` `globalEnv`, keeping it alphabetical; Turborepo's strict mode hides undeclared variables from tasks and leaves them out of cache keys. 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 the Shopify scripts gate: Shopify analytics, standalone consent, and WebMCP use the required numeric `NEXT_PUBLIC_SHOPIFY_SHOP_ID`. Build the ShopifyScripts props from configuration rather than making a shop-data request: ```tsx import type { ShopifyScriptsI18n, ShopifyScriptsShop } from "@shopify/hydrogen"; import { GoogleTagManager } from "@next/third-parties/google"; import { Analytics } from "@vercel/analytics/next"; import { SpeedInsights } from "@vercel/speed-insights/next"; import { isShopifyScriptsEnabled, shopConfig } from "@/lib/config"; import { ShopifyScriptsTracker } from "./shopify-client"; export function AnalyticsComponents() { const gtmId = process.env.NEXT_PUBLIC_GTM_ID; const i18n: ShopifyScriptsI18n = { country: shopConfig.localization.country, language: shopConfig.localization.language, }; const shop: ShopifyScriptsShop = { myshopifyDomain: process.env.NEXT_PUBLIC_SHOPIFY_STORE_DOMAIN as string, shopId: process.env.NEXT_PUBLIC_SHOPIFY_SHOP_ID as string, storefrontId: process.env.NEXT_PUBLIC_SHOPIFY_STOREFRONT_ID ?? "", }; return ( <> {shopConfig.analytics.vercel.isEnabled ? : null} {shopConfig.analytics.speedInsights.isEnabled ? : null} {gtmId ? : null} {isShopifyScriptsEnabled && } ); } ``` 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 or consent. The storefront sends page, product, collection, search, cart-view, and confirmed cart-change events through Hydrogen's analytics bus when Shopify scripts are enabled. Shopify analytics is disabled by default. Set the required `NEXT_PUBLIC_SHOPIFY_SHOP_ID` before building the storefront. Use the numeric Shopify shop ID, not the Headless storefront ID. To turn Shopify's built-in analytics destination and consent integration on, set `analytics.shopify.isEnabled` to `true` in `lib/config/index.ts`. To load Shopify consent without its analytics destination, set `analytics.shopify.consent.isEnabled` to `true`. WebMCP also loads Shopify scripts and consent without enabling the analytics destination. Consent mode is set by `analytics.shopify.consent.mode` 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`; mount Shopify scripts when Shopify analytics, consent, or WebMCP is enabled. - 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 `