. Oxygen Oxygen serves as the deployment target for Hydrogen apps, executing SSR at the edge. Unlike traditional cloud hosting, Oxygen pre-renders pages globally, reducing TTFB. Oxygen’s runtime optimizes video delivery by caching immutable assets like thumbnails and manifests while delegating adaptive bitrate streaming (e.g., HLS or DASH) to the client. This edge-native approach minimizes latency for global audiences but requires careful cache-control headers to avoid stale video segments during updates. The shopify.config.toml file defines deployment rules: # Example: shopify.config.toml [build] command = 'npm run build' output = 'dist'
[edge] routes = [ { from = '/videos/*', to = '/cdn/videos' } ] Explanation : Specifies a shopify.config.toml configuration file for setting up a Hydrogen or Shopify storefront environment. Under [build] , it defines the build command as npm run build and sets the output directory to dist . Under [edge] , configures edge routing: any request matching /videos/* is redirected to /cdn/videos . Note : Oxygen does not support custom server logic; all dynamic behavior must reside in Hydrogen’s frontend or Shopify’s backend APIs. Hosting Environment and Infrastructure Hydrogen Hydrogen operates as a Vite-powered frontend framework, designed to run on Node.js during development and build phases. It outputs static assets and server entry points compatible with Oxygen or alternative hosting platforms. For video workflows, Hydrogen’s local development server simulates SSR behavior, but video streaming performance varies due to the absence of edge-network conditions. CDN behaviors must be mocked to accurately test adaptive streaming logic. Oxygen Oxygen provides a purpose-built edge hosting environment, leveraging Shopify’s global infrastructure to deploy Hydrogen apps. It automatically provisions edge functions that handle SSR and API proxying to reduce cold starts for dynamic routes. Video assets benefit from Oxygen’s built-in CDN to support byte-range requests for partial content streaming. However, Oxygen does not transcode videos; media must be pre-processed into formats like HLS before deployment. Local Development and Tooling Hydrogen Hydrogen’s toolchain includes Vite for fast HMR and a Shopify CLI plugin for storefront data mocking. The local dev server supports SSR out of the box, but video streaming tests require manual configuration of local proxies to simulate edge caching. Debugging performance bottlenecks in video playback often involves analyzing network waterfalls in Chrome DevTools, as Oxygen’s edge-specific behaviors are not fully replicable locally. Oxygen Oxygen lacks a local runtime; testing requires pushing builds to Shopify’s staging environment. This creates friction when debugging edge-specific issues like cache-hit ratios for video segments. Oxygen’s logging and real-user monitoring (RUM) help diagnose playback failures, though this feedback loop is slower than local debugging. Shopify’s admin API provides some cache purging controls, but fine-grained video cache management remains limited. Edge Deployment and Caching Strategy Hydrogen Hydrogen apps define caching rules via response.headers in server components or route loaders. For video content, immutable assets like thumbnails use long-lived Cache-Control headers, while dynamic manifests respect shorter TTLs. However, cache invalidation relies on Oxygen’s implementation to follow Shopify’s edge network policies. // Example: Cache headers in Hydrogen route export async function api(request) { return new Response(stream, { headers: { 'Cache-Control': 'public, max-age=86400, immutable', 'Content-Type': 'application/vnd.apple.mpegurl', }, }); } Explanation : Defines an api route in Hydrogen using an async function that returns a streamed response. Sets Cache-Control header to allow public caching for 24 hours ( 86400 seconds) and marks the response as immutable . Sets the Content-Type to application/vnd.apple.mpegurl , used for HLS playlist files. Oxygen Oxygen enforces edge caching with customizable rules for routes and assets. Video files benefit from automatic geo-replicated storage, but adaptive streaming requires explicit cache segmentation for each bitrate variant. Oxygen does not support on-the-fly video transcoding, so all renditions must be pre-generated and uploaded. Cache purging is eventually consistent, which can delay updates to video playlists during sales events. # Example: oxygen.toml for video routes [edge] routes = [ { from = '/videos/*', to = '/cdn/videos', headers = { 'Cache-Control' = 'public, max-age=31536000' } } ] Explanation : Configures an edge route in oxygen.toml to rewrite all /videos/* requests to /cdn/videos . Adds a Cache-Control header to allow public caching for one year ( 31536000 seconds). This setup optimizes performance for static video content by enabling long-term edge caching. Deployment Workflow and CI/CD Integration Hydrogen Hydrogen projects integrate with GitHub Actions or similar CI systems to trigger builds via the Shopify CLI. The build process generates static assets and server bundles, which deploy to Oxygen via shopify hydrogen deploy . For video-heavy stores, CI pipelines must include media processing steps (e.g., FFmpeg transcoding) before uploading to Shopify’s CDN. Deployment rollbacks are possible, but do not revert media assets. # Example: GitHub Actions workflow jobs: deploy: steps: - name: Deploy to Oxygen run: shopify hydrogen deploy - name: Upload Videos run: aws s3 sync ./videos s3://shopify-cdn/videos Explanation: Defines a GitHub Actions workflow job named deploy for automating deployment tasks. Runs shopify hydrogen deploy to deploy the Hydrogen storefront to Oxygen. Uses aws s3 sync to upload local video assets to an S3 bucket ( shopify-cdn/videos ) for CDN delivery. Oxygen Oxygen deployments are atomic for consistent SSR behavior across edge locations. However, media assets deploy separately via the Shopify Files API, creating a split workflow. CI/CD pipelines must coordinate between Hydrogen app updates and video uploads to avoid version mismatches. Oxygen’s edge rollout is near-instantaneous, but CDN propagation for new videos can take minutes. Authentication, Middleware, and Route Management Hydrogen Hydrogen handles authentication logic via Shopify’s Storefront API or third-party OAuth providers. Middleware functions run in Node.js during SSR, enabling cookie-based sessions or JWT validation before rendering video-gated content. Route management uses file-based conventions, with support for dynamic parameters (e.g., /products/:handle/video ). Video access control checks often occur in route loaders to prevent unauthorized streaming. Oxygen Oxygen executes Hydrogen’s middleware at the edge, reducing latency for auth checks. However, edge functions have shorter execution timeouts, requiring stateless authentication designs. Route-level caching can conflict with private video content, necessitating Vary headers for user-specific manifests. Oxygen does not support custom edge middleware beyond Hydrogen’s built-in capabilities. # Example: A/B route in oxygen.toml [[edge.routes]] from = '/product/video' to = [ { path = '/video-a', condition = 'cookie:ab_test=variant_a' }, { path = '/video-b', condition = 'cookie:ab_test=variant_b' } ] Explanation: Configures an A/B testing route in oxygen.toml for the /product/video path. Uses conditional routing based on the ab_test cookie value. Routes users with ab_test=variant_a to /video-a , and those with ab_test=variant_b to /video-b . Integration with Shopify APIs and Storefront Data Hydrogen Hydrogen queries Shopify’s Storefront API via GraphQL, with built-in support for stale-while-revalidate (SWR) caching. Video metadata (e.g., product demo clips) is fetched during SSR, while user-specific data (e.g., watch progress) loads client-side. The framework’s useShopQuery hook deduplicates API calls, but video-centric stores often bypass it for direct CDN requests to reduce latency. Oxygen Oxygen proxies Storefront API calls through the edge, reducing round-trip times. However, video stores frequently bypass this for direct CDN access to media APIs like Mux or Cloudflare Stream. Oxygen’s edge location influences API latency, with regional data residency requirements impacting video analytics collection. Shopify’s rate limits apply uniformly, regardless of Oxygen’s geographic distribution. Video Centric Workflow Difference Video Asset Management Hydrogen Video content in Hydrogen is typically linked via Shopify metafields, allowing content teams to manage video URLs (from platforms like Mux or S3) without modifying code. These URLs are queried at build or request time using GraphQL. Hydrogen does not bundle video files with the app; instead, it fetches video URLs dynamically during SSR. Developers often use client-side logic (like IntersectionObserver ) to lazy-load players and avoid unnecessary bandwidth consumption. Example : // Example: GraphQL metafield query metafield(namespace: 'media', key: 'hero_video') { value } Explanation : Queries the hero_video metafield from the 'media' namespace to retrieve the stored video URL for a specific product. This value is typically used to dynamically load and render a video player in Hydrogen. Oxygen Oxygen does not handle video uploads or transcoding. Instead, it relies on pre-processed video assets hosted on external CDNs or uploaded via the Shopify Files API. The deployment process must ensure all video content is ready and accessible before pushing updates. Edge caching plays a critical role in video performance. Oxygen routes video requests through specified paths in oxygen.toml and applies long-lived caching headers for immutable assets. Example : # Example: Cache setup for Oxygen [edge] routes = [ { from = '/videos/*', to = '/cdn/videos', headers = { 'Cache-Control' = 'public, max-age=31536000' } } ] Explanation : Defines an edge route that rewrites requests from /videos/* to /cdn/videos . Applies a Cache-Control header with a one-year ( 31536000 seconds) cache duration for long-term caching of static video content at the edge for improved performance. Product-Specific Video Rendering Hydrogen Hydrogen supports dynamic video rendering on a per-product basis using metafields and conditional logic. Video components are often wrapped in React’s Suspense to handle fallback content while the video player loads. Example : // Example: Product video rendering with fallback
}> {videoUrl ?
:
} Explanation : Wraps the video rendering logic in a Suspense component to allow a fallback (
) to be shown while the video is loading. If videoUrl is available (fetched via a metafield), the video player is rendered; otherwise, a static product image is used. Oxygen Oxygen streams these components at the edge using streamReactComponents() to enhance performance during server-side rendering. However, Oxygen cannot render or manipulate video content itself. All video rendering logic must live inside Hydrogen components. The player component still loads client-side, but Oxygen’s role is to deliver the required metadata and assets with minimal delay via edge SSR. Performance Optimization Hydrogen Hydrogen optimizes video delivery by combining lazy hydration, responsive source selection, and direct CDN access. Developers use the native
Video Hosting
Image Hosting
Galleries
Video Messaging
CincoTube
Pages
Live
