Shopify Hydrogen Quickstart

Shopify Hydrogen storefronts use React Server Components and streaming SSR on Shopify's Oxygen hosting platform. While Hydrogen provides server-side rendering, dynamic content like personalized recommendations, deferred data loading, and client-side hydration can leave gaps in what search engines and AI crawlers actually index. PerfectSearch fills those gaps using the DNS proxy mode with your Oxygen deployment URL as the origin.

Why does Hydrogen need PerfectSearch?

Hydrogen uses React SSR with streaming, which means the initial HTML response may not contain all the content that appears after hydration and deferred data loading. Search engine crawlers have limited JavaScript execution capabilities, and AI crawlers often do not execute JavaScript at all. This means product reviews, dynamic pricing, personalized sections, and lazy-loaded content may be invisible to bots.

• Deferred data (using Remix defer) loads after the initial HTML shell
• Client-side product filtering and sorting is invisible to crawlers
• Dynamic pricing from Shopify APIs may not be included in the SSR pass
• AI crawlers like ChatGPT, Claude, and Perplexity do not run JavaScript

How do I set up PerfectSearch for Hydrogen?

Setting up PerfectSearch for a Hydrogen storefront uses the DNS proxy mode, which requires no code changes to your Hydrogen app. You create a site in the dashboard, configure a CNAME record, and set your Oxygen deployment URL as the origin. The entire process takes under 10 minutes and does not require redeploying your storefront.

1. Create a site — Log in to the PerfectSearch dashboard and click Add Site. Enter your storefront domain (e.g., shop.example.com).
2. Select DNS Proxy mode— Choose "DNS Proxy" as the integration mode. This is the recommended mode for all Hydrogen storefronts.
3. Configure your CNAME — Add a CNAME record in your DNS provider pointing your domain to the PerfectSearch edge:

Type:  CNAME
Name:  shop.example.com
Value: shop-example-com.edge.perfectline.io

4. Set your origin URL — In the dashboard under Settings, enter your Oxygen deployment URL as the origin (see the next section for details).
5. Wait for DNS propagation — This typically takes 5 to 30 minutes. TLS certificates are provisioned automatically on the first request.

What should I use as my origin URL?

The origin URL should be the Oxygen deployment URL that serves your Hydrogen storefront before the CNAME redirect takes effect. This is the URL that Shopify assigns to your Oxygen deployment. You can find it in your Shopify Partners dashboard or in the Hydrogen deployment output. Use the URL that resolves to your storefront directly, before any custom domain configuration.

# Default Oxygen URL
https://your-store.myshopify.com

# Oxygen deployment URL (from Shopify Partners dashboard)
https://oxygen-abc123.myshopify.dev

# Custom domain (before CNAME change)
https://shop.example.com

If you are using a custom domain that will be CNAMEd to PerfectSearch, make sure to set the origin URL before updating the DNS record. Use the Oxygen deployment URL (e.g., *.myshopify.dev) rather than the custom domain to avoid a redirect loop.

How do I verify product pages are visible?

After DNS propagation completes and your first snapshots have been generated, use the PerfectSearch Visibility Test tool to verify that your product pages are fully rendered for bots. Enter a product page URL and check that the snapshot includes the complete product title, description, pricing, images, and structured data. Pay special attention to content that loads via deferred data or client-side JavaScript.

Open the Visibility Test tool →

Key things to check

• Product title, description, and price are present in the snapshot
• Product images have proper alt text in the rendered HTML
• Collection pages show all products, not just the initial server-rendered batch
• Product reviews and ratings are included if present on the page
• JSON-LD structured data (Product schema) is complete and accurate