Docs
    Shopify Headless StorefrontUpdated May 23, 2026MD

    Rock Paper Scissors Headless Storefront

    Markdown file

    README.md

    Rock Paper Scissors Headless Storefront

    Headless Shopify storefront built with Next.js App Router.

    Features

    • Shopify catalog, collections, cart, and checkout handoff
    • SSR-native product and collection cards across homepage and catalog surfaces
    • Collection cards fallback to first product featured image when collection image is missing
    • Product cards show explicit pricing ($X or $X–$Y) on listing surfaces
    • Judge.me-powered product ratings/reviews on PDPs + product cards, with in-store review submission form
    • Store-wide review aggregate badge and dedicated /reviews page with recent customer feedback
    • Product-card UX aligned with Shopify storefront design patterns (without runtime web-component dependency)
    • SSR homepage intro with taxonomy quick links derived from Shopify metafield-driven navigation
    • Shopify-backed blog/article compatibility routes (pre-1020 bridge, enabled by default):
      • /blogs
      • /blogs/[blog]
      • /blogs/[blog]/[article]
    • Shopify-driven branding (store name, logo, and square logo for metadata icons)
    • Navigation and footer menus from Shopify menu handles
    • Dawn-parity taxonomy navigation:
      • desktop Shop by Artist and Shop by Subject mega groups
      • mobile taxonomy drawer sections
      • shared featured collection tiles from collection metafields
    • Legacy Shopify URL parity routes (/collections/*, /pages/*, /policies/*)
    • Taxonomy landing pages: /shop-by-artist, /shop-by-subject
    • Customer Account API login/session scaffold (/account) with profile, recent orders, and saved addresses
    • Quick add on product cards with variant picker support
    • Homepage "New Arrivals" grid for resilient catalog visibility
    • Tokenized design foundation (--rps-*) and expanded style-guide coverage for nav, hero, filter/sidebar, CTA, blog, account, and footer modules
    • Google Merchant Center feed at /api/feeds/google (full-catalog, variant-level)
    • Feature-flagged agent commerce API routes:
      • GET /api/agents/catalog
      • POST /api/agents/checkout
    • JSON landing pages at /landing/[slug]
    • LLM discovery endpoint at /llms.txt
    • Extended LLM discovery endpoint at /llms-full.txt
    • SEO/GEO automated audit command: pnpm seo:audit <base-url>
    • Shopify-to-headless parity audit command: pnpm parity:audit --base-url <base-url>
    • Feed-vs-PDP identifier parity audit command: pnpm shopify:audit:identifier-parity -- --base-url <base-url>
    • Approval-gated Shopify metadata remediation apply command: pnpm shopify:apply:metadata-remediation -- --plan <path> [--apply --approve APPLY_METADATA_REMEDIATION]
    • Dedicated SEO/GEO governance CI workflow (blocking technical checks + non-blocking catalog quality reporting)

    Local Setup

    1. Copy .env.example to .env and fill required values.
    2. Install dependencies.
    3. Start the dev server.
    pnpm install
pnpm dev

    If you are working from a non-main Git worktree and update local env values, sync them back to the main checkout with:

    pnpm env:sync

    To inspect whether the current worktree and main checkout are drifting before you sync, run:

    pnpm env:status

    Canonical setup and bootstrap guidance lives in:

    • docs/development/environment-bootstrap-and-sync.md
    • docs/development/programmatic-growth-reporting.md

    Required Environment Variables

    Use .env.example as the tracked schema, .env as the live local values, and docs/development/environment-bootstrap-and-sync.md as the repo-owned bootstrap runbook.

    • SHOPIFY_STORE_DOMAIN
    • SHOPIFY_STOREFRONT_ACCESS_TOKEN
    • SHOPIFY_REVALIDATION_SECRET
    • COMPANY_NAME
    • SITE_NAME
    • SITE_DESCRIPTION

    Optional:

    • SITE_URL (explicit canonical public origin; recommended for production and feed-channel cutovers)
    • SHOPIFY_API_KEY (preferred Shopify Admin app credential for token exchange)
    • SHOPIFY_API_SECRET (preferred Shopify Admin app credential for token exchange)
    • SHOPIFY_ADMIN_ACCESS_TOKEN (optional legacy/manual Admin fallback; not the preferred primary path)
    • SHOPIFY_CUSTOM_ARTWORK_PUBLICATIONS (optional comma-separated publication-name override for custom-artwork provisioning)
    • SHOPIFY_HEADER_MENU_HANDLE (default: main-menu)
    • SHOPIFY_FOOTER_MENU_HANDLE (default: footer)
    • SHOPIFY_BLOGS_DISABLED (default: false; set true only to hide temporary Shopify-backed /blogs* compatibility routes)
    • SHOPIFY_AGENTIC_ENABLED (default: false; enables /api/agents/* routes)
    • SHOPIFY_AGENTIC_CATALOG_MODE (default: readonly; set checkout to enable checkout-prep endpoint)
    • SHOPIFY_AGENTIC_ALLOWED_ORIGINS (comma-separated origin allowlist for agent API callers)
    • SHOPIFY_AGENTIC_STOREFRONT_ACCESS_TOKEN (optional dedicated token for /api/agents/*; falls back to SHOPIFY_STOREFRONT_ACCESS_TOKEN)
    • SHOPIFY_MENU_INTERNAL_HOSTS (comma-separated domains treated as internal links)
    • SHOPIFY_TAXONOMY_NAMESPACE / SHOPIFY_TAXONOMY_*_KEY (defaults match Dawn collection metafields: is_nav, by_artist, by_subject, is_featured; optional ranking key: featured_rank)
    • SHOPIFY_TAXONOMY_SHOW_ARTIST_MENU / SHOPIFY_TAXONOMY_SHOW_SUBJECT_MENU (default: true)
    • SHOPIFY_TAXONOMY_ARTIST_TITLE / SHOPIFY_TAXONOMY_SUBJECT_TITLE
    • SHOPIFY_TAXONOMY_ARTIST_VIEW_ALL_LABEL / SHOPIFY_TAXONOMY_SUBJECT_VIEW_ALL_LABEL
    • SHOPIFY_TAXONOMY_ARTIST_VIEW_ALL_PATH / SHOPIFY_TAXONOMY_SUBJECT_VIEW_ALL_PATH
    • SHOPIFY_MEGA_MENU_NAMESPACE / SHOPIFY_MEGA_MENU_*_KEY
    • SHOPIFY_CUSTOMER_ACCOUNT_CLIENT_ID
    • SHOPIFY_CUSTOMER_ACCOUNT_CLIENT_SECRET
    • SHOPIFY_CUSTOMER_ACCOUNT_SHOP_DOMAIN (defaults to SHOPIFY_STORE_DOMAIN)
    • SHOPIFY_CUSTOMER_ACCOUNT_ORIGIN (used for Customer Account API token/profile requests)
    • SHOPIFY_CUSTOMER_ACCOUNT_SCOPES (default: openid email customer-account-api:full)
    • SHOPIFY_CUSTOMER_ACCOUNT_REDIRECT_URI
    • SHOPIFY_CUSTOMER_ACCOUNT_LOGOUT_REDIRECT_URI
    • VERCEL_AUTOMATION_BYPASS_SECRET (optional, enables protected-deployment audits/e2e)
    • PLAYWRIGHT_BASE_URL (set to run e2e against an existing deployed URL instead of local dev server)
    • NEXT_PUBLIC_GA_MEASUREMENT_ID
    • JUDGEME_SHOP_DOMAIN (defaults to SHOPIFY_STORE_DOMAIN)
    • JUDGEME_PUBLIC_TOKEN (required for review/rating display)
    • JUDGEME_PRIVATE_TOKEN (required for review submission)
    • GOOGLE_MERCHANT_DEFAULT_BRAND (optional fallback brand when Shopify product vendor is blank)
    • GA4_PROPERTY_ID (required for the 1085 GA4 reporting runner)
    • GSC_SITE_URL (required for the 1085 Search Console reporting runner)
    • GOOGLE_APPLICATION_CREDENTIALS (absolute path to the recurring reporting service-account JSON)
    • GOOGLE_OAUTH_CLIENT_CREDENTIALS (absolute path to the Desktop OAuth client JSON used for one-off human-admin Merchant registration flows)
    • GOOGLE_CLOUD_PROJECT_ID (current reporting project: shopify-rps)
    • GOOGLE_MERCHANT_ACCOUNT_ID (current child Merchant account: 486364000)
    • GOOGLE_MERCHANT_PARENT_ACCOUNT_ID (current parent Merchant MCA: 459833598)
    • GOOGLE_MERCHANT_DEVELOPER_EMAIL (current Merchant developer/admin email)
    • SEO_AUDIT_MAX_SITEMAP_URLS (optional; default 80)
    • SEO_AUDIT_TIMEOUT_MS (optional; default 20000)
    • SEO_AUDIT_RETRIES (optional; default 1)
    • SEO_AUDIT_FAIL_ON_WARNINGS (optional; default false)

    Useful Commands

    • pnpm build - production build
    • pnpm test - format + unit tests
    • pnpm test:unit - run Vitest unit suite
    • pnpm test:coverage - run Vitest with enforced coverage thresholds
    • pnpm test:ci - format + media-ledger drift check + coverage gate used by CI quality job
    • pnpm test:e2e - run Playwright e2e suite
    • pnpm test:e2e:install - install Playwright Chromium dependencies
    • pnpm test:all - format + unit + e2e
    • pnpm seo:audit <base-url> - SEO/GEO + structured-data audit
    • pnpm seo:audit:fixture - strict SEO/GEO contract audit against a self-started local mock fixture (no Shopify secrets required)
    • pnpm parity:audit --base-url <base-url> - Shopify catalog/page/policy parity + navigation audit
    • pnpm shopify:audit:identifier-parity -- --base-url <base-url> - sample feed-vs-PDP identifier parity audit for live storefront URLs
    • pnpm agent:catalog:audit - Shopify catalog metadata quality audit for agentic commerce readiness
    • pnpm shopify:plan:metadata-remediation -- --json <path> - dry-run remediation plan for strict Shopify metadata gaps
    • pnpm shopify:apply:metadata-remediation -- --plan <path> - dry-run safe-metadata apply preview (no Shopify writes)
    • pnpm shopify:apply:metadata-remediation -- --plan <path> --apply --approve APPLY_METADATA_REMEDIATION - execute approval-gated safe-metadata apply mutations
    • pnpm shopify:audit:handle-quality -- --json <path> - read-only product/collection handle-length quality baseline
    • pnpm shopify:plan:handle-normalization -- --json <path> - deterministic product-handle normalization plan (no Shopify writes)
    • pnpm shopify:apply:handle-normalization -- --plan <path> - dry-run handle-apply selection preview (no Shopify writes)
    • pnpm shopify:apply:handle-normalization -- --plan <path> --apply --approve APPLY_HANDLE_NORMALIZATION - execute approval-gated product-handle updates with redirectNewHandle safety
    • pnpm shopify:media-ledger:build - rebuild the generated Shopify product-media change ledger from committed evidence artifacts
    • pnpm shopify:media-ledger:check - verify the generated Shopify product-media change ledger has not drifted from committed evidence artifacts
    • pnpm docs:links - docs link checker
    • pnpm docs:manifest - regenerate docs manifest
    • pnpm growth:reports:stack-check - verify GA4, GSC, GA Admin, and Merchant reporting setup
    • pnpm growth:reports:cycle -- --compare previous_period - run the full recurring 1085 reporting packet
    • pnpm env:status - compare .env and .env.example drift between the active worktree and the main checkout
    • pnpm env:sync - sync .env and .env.example between the active worktree and the main checkout
    • pnpm env:bootstrap - print the repo bootstrap summary from the tracked env-manager config
    • pnpm env:sync-main-worktree - compatibility alias for the older sync command

    Shopify Credential Model

    • SHOPIFY_STOREFRONT_ACCESS_TOKEN
      • storefront-only runtime access for customer-facing reads
    • SHOPIFY_API_KEY + SHOPIFY_API_SECRET
      • preferred Admin app auth for provisioning, uploads, and admin-side automation
    • SHOPIFY_ADMIN_ACCESS_TOKEN
      • optional fallback only; keep this separate from storefront credentials

    Recommended auth order for admin operations:

    1. SHOPIFY_API_KEY + SHOPIFY_API_SECRET
    2. SHOPIFY_ADMIN_ACCESS_TOKEN
    3. legacy fallback behavior only when a private Admin-style token is still present in SHOPIFY_STOREFRONT_ACCESS_TOKEN

    Docs

    • System docs index: docs/README.md
    • Headless setup: docs/HEADLESS_KICKOFF.md
    • Shopify runtime validation: docs/development/shopify-validation.md
    • Environment/bootstrap runbook: docs/development/environment-bootstrap-and-sync.md
    • Unified Google reporting/bootstrap runbook: docs/development/programmatic-growth-reporting.md
    • SEO/GEO audit runbook: docs/development/seo-geo-audit.md
    • SEO/GEO governance CI workflow: .github/workflows/seo-geo-governance.yml

    Project lifecycle folders:

    • docs/PROJECTS/active/ - in progress
    • docs/PROJECTS/in-review/ - implementation complete, awaiting walkthrough/sign-off
    • docs/PROJECTS/blocked/ - waiting for user decisions/permissions/input
    • docs/PROJECTS/completed/ - delivered after walkthrough/sign-off