Skip to content

Migrate Shopify Inbox to the official <shopify-chat> web component #467

Description

@paul-phan

Context

Hydrogen's July 30, 2026 developer preview adds official Shopify Inbox support through ShopifyScripts and the <shopify-chat> web component:

<ShopifyScripts
  shop={{shopId, storefrontId, myshopifyDomain}}
  inbox
/>
<shopify-chat />

Release notes: https://hydrogen.shopify.dev/update/developer-preview-release-notes-july-30-2026

Pilot currently uses the legacy shopifyChatV1.js loader in app/components/shopify-inbox.tsx, requires PUBLIC_SHOPIFY_INBOX_SHOP_ID, and relies on private widget selectors for its custom trigger. This was introduced in #338 and the overlay behavior was added in #447.

Do not implement this against @shopify/hydrogen@preview. The preview is incompatible with the current Pilot stack. Start once Shopify publishes the API in a stable Hydrogen release with migration guidance.

Scope

  • Replace the legacy loader with ShopifyScripts using inbox.
  • Render <shopify-chat> in the root layout.
  • Remove PUBLIC_SHOPIFY_INBOX_SHOP_ID, legacy URL/query construction, and obsolete setup documentation.
  • Preserve the overlay visibility behavior and the custom "Message us" action using Shopify's documented public web-component API only.
  • Verify CSP, nonce handling, consent, analytics, locale, and client-side navigation.
  • Update .weaverse/docs/shopify-inbox.md, .env.example, and relevant types.

Acceptance criteria

  • Uses a stable @shopify/hydrogen release that officially exports ShopifyScripts.
  • Inbox loads through <ShopifyScripts inbox> and <shopify-chat> without the legacy loader or Inbox-specific shop ID.
  • The widget remains hidden while Pilot drawers, dialogs, and popups are open.
  • The custom "Message us" action opens chat without private Shadow DOM selectors.
  • Missing or disabled Inbox configuration degrades safely without breaking the storefront.
  • Verified on a deployed domain on desktop and mobile with no CSP or console errors.
  • Verified AI-agent chat and staff handoff with "Require sign-in to chat with staff" disabled.
  • Build, typecheck, and relevant tests pass.
  • Setup and migration documentation is updated.

Metadata

Metadata

Assignees

Labels

enhancementNew feature or request

Type

No type

Projects

Status
Todo

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions