How to Add Shopify's New <shopify-account> Component to Your Hydrogen Storefront
Shopify just dropped official docs for the <shopify-account> web component — a native way to let customers sign in directly from your Hydrogen storefront without leaving the page.
If you've ever wrestled with Hydrogen's Customer Account API setup, this is the simplest auth flow you've seen yet.
What Is the <shopify-account> Component?
It's a Storefront Web Component that handles the full customer sign-in flow. Drop it in your header, pass two tokens, and your customers get a seamless login experience — all without custom auth routes.
Two tokens required:
public-access-token→ fromPUBLIC_STOREFRONT_API_TOKENin your.envcustomer-access-token→ from the Customer Account API after authentication
Prerequisites
Before you start:
- Hydrogen storefront deployed to Oxygen (Getting started guide)
- Customer Account API configured (Tutorial here)
- Storefront API permissions in Shopify Admin:
unauthenticated_read_customersunauthenticated_read_contentunauthenticated_read_product_listings
Step 1: Load the Account Component Bundle
The bundle isn't included in the default Hydrogen scaffold. Load it via CDN in /app/root.jsx:
import { Script } from '@shopify/hydrogen';// Inside <head> of Layout component:<Script src="https://cdn.shopify.com/storefront/web-components/account.js" />
Step 2: Update /app/root.jsx Loader
Pass both publicAccessToken and customerAccessToken down to child components:
export async function loader({ context }) {const { storefront, customerAccount } = context;// Get public storefront tokenconst publicAccessToken = context.env.PUBLIC_STOREFRONT_API_TOKEN;// Get customer token (if authenticated)const customerAccessToken = await customerAccount.getAccessToken();return defer({publicAccessToken,customerAccessToken,// ...other loader data});}
Step 3: Update PageLayout.jsx
Pass the tokens through to your layout and add proper TypeScript types:
// Add to @property JSDoc near bottom of file:// * @property {string} publicAccessToken// * @property {string} customerAccessToken
Step 4: Replace the Sign In Button in Header.jsx
Swap the default "Sign In" link for the <shopify-account> component:
function HeaderCtas({ publicAccessToken, customerAccessToken }) {return (<nav><shopify-accountsign-in-url="/account/login"public-access-token={publicAccessToken}customer-access-token={customerAccessToken}/>{/* Cart icon, etc. */}</nav>);}
Note:
sign-in-urlshould point to your authorization request page — default is/account/loginin Hydrogen.
Step 5: Upgrade for Better Login UX (Hydrogen ≥ 2025.7.3)
If you're on @shopify/hydrogen 2025.7.3+, update /app/routes/account_.login.jsx to use the improved login options:
// Use the new login() options for better UXconst loginUrl = await customerAccount.login({// Additional options now available});
Check the full API docs for all available options.
Styling
The component is fully stylable via CSS. Refer to the Storefront Web Components docs for CSS custom properties.
Important: No Localhost Support
The Customer Account API doesn't work on localhost. You'll need to deploy to Oxygen to test:
shopify hydrogen deploy
Test on your production URL after deployment.
Why This Matters for Weaverse Users
If you're building a Weaverse-powered Hydrogen store, this component drops directly into your theme's header section. No custom auth logic needed.
Coming soon: Native <shopify-account> support in Weaverse sections — stay tuned.
TL;DR
| Step | File | Action |
|---|---|---|
| 1 | root.jsx | Load CDN bundle + pass tokens from loader |
| 2 | PageLayout.jsx | Thread tokens to child components |
| 3 | Header.jsx | Replace Sign In with <shopify-account> |
| 4 | account_.login.jsx | Update if on Hydrogen ≥ 2025.7.3 |
Official docs: https://shopify.dev/docs/storefronts/headless/bring-your-own-stack/hydrogen-with-account-component
