How to Build Custom Storefronts with Shopify Oxygen?

Shopify Oxygen gives developers full control over storefront design using React while relying on Shopify's backend for commerce operations. It combines Hydrogen for development and Oxygen for global hosting. This stack is especially useful when standard Liquid themes limit performance, UX flexibility, or branding needs.

With Hydrogen, developers use modern tools like React, Vite, and server-side rendering (SSR) to build storefronts from scratch. Shopify’s Storefront API connects the frontend to Shopify’s backend for handling products, carts, and checkout. Once built, Oxygen takes care of deployment and edge hosting.

Starting with Hydrogen

Development begins with Hydrogen, a framework that brings server-side rendering and commerce-ready components into a React environment. To create a new Hydrogen project:

code

npm init @shopify/hydrogen

Once the setup is complete, navigate into your project folder:

code

npm run dev

The development server starts with hot reload support. You’ll see changes instantly in the browser, which makes iteration fast and straightforward.

Customizing Layout and Pages

Hydrogen projects are structured around React and file-based routing. Each page corresponds to a file inside the routes/ directory. To display featured collections, you can write a GraphQL query and render the response inside a component:

code

const QUERY = gql`

code

query FeaturedCollections {

code

collections(first: 3) {

code

nodes {

code

id

code

title

code

handle

code

image {

code

url

code

Hydrogen gives you full control over the markup, layout, and interaction behavior. You’re not limited by theme templates or opinionated structure. This makes it easier to create storefronts that exactly match your UI goals.

File-Based Routing

Hydrogen uses file-based routing, so every .jsx file in the routes/ folder maps directly to a URL. For example, this file:

code

routes/products/[handle].jsx

code

automatically becomes a dynamic product page accessible at:

code

/products/your-product-handle

Here’s a simplified example of what might live inside that file to make routing predictable, reduce boilerplate, and help you organize pages as your storefront grows. You can also wrap routes with shared layouts, such as navigation bars or footers, using App.server.jsx.

code

export default function ProductPage({params}) {

code

const {handle} = params;

code

const {data} = useShopQuery({

code

query: PRODUCT_QUERY,

code

variables: {handle}

code

});

code

return (

code

<div>

code

<h1>{data.product.title}</h1>

code

<img src={data.product.images.nodes[0].url} />

code

</div>

code

);

code

Integrating Video into Your Storefront

Video helps bring products to life and makes your storefront more engaging. Hydrogen supports both hosted and embedded video with minimal setup. To embed a YouTube video:

code

<iframe

code

width="100%"

code

height="400"

code

src="https://www.youtube.com/embed/YOUR_VIDEO_ID"

code

frameBorder="0"

code

allowFullScreen

code

/>

You can pull video URLs dynamically from your CMS or Shopify metafields. For example, on a product page, you can load the video based on the product handle and stream it alongside other data. Hydrogen supports lazy loading, so you can defer loading media that isn’t immediately visible, improving page performance.

Example: Adding a Self-Hosted Video that Plays Silently in the Background

code

<video

code

autoPlay

code

muted

code

loop

code

playsInline

code

style={{ width: '100%', height: 'auto' }}

code

<source src="/videos/demo.mp4" type="video/mp4" />

code

</video>

Deploying to Oxygen

After development, deploy the storefront to Oxygen, Shopify’s global hosting platform. It automatically handles server-side rendering at the edge.

Step 1: Connect the project to your Shopify store.

code

shopify link

Step 2: Deploy Your Storefront

code

shopify hydrogen deploy

Once deployed, the app is hosted globally with automatic scaling and fast response times. Preview links are generated for branches and pull requests, which makes testing with teams easier.

Environment Setup

Hydrogen projects often need environment-specific values like API tokens, store domains, or feature flags. You can define these in a .env file:

code

PUBLIC_STORE_DOMAIN=my-store.myshopify.com

code

PRIVATE_STOREFRONT_API_TOKEN=abc123

These variables are available during development and deployment. Keep secrets like API tokens out of your codebase and configure production values through Shopify’s admin interface for each Oxygen deployment.

Performance and Streaming

Hydrogen uses React Server Components and supports streaming, which allows pages to render progressively. This means initial page elements load fast and content appears in sections as data becomes available. For example, the product title and price can render immediately, while related products or video content stream in seconds. This improves perceived performance and keeps the experience responsive. No manual setup is needed; Hydrogen and Oxygen handle this out of the box.

Debugging and Logs

If something goes wrong during deployment or rendering, Oxygen provides access to logs directly in the Shopify admin. You can view real-time logs, trace errors back to specific files, and test different branches using preview URLs. During local development, browser dev tools still work as expected for inspecting requests, debugging components, and monitoring performance.

How to Build Custom Storefronts with Shopify Oxygen?

Starting with Hydrogen

Customizing Layout and Pages

File-Based Routing

Integrating Video into Your Storefront

Deploying to Oxygen

Environment Setup

Performance and Streaming

Debugging and Logs

Was this article helpful?