Articles
references: https://shopify.dev/docs/storefronts/headless/hydrogen/fundamentals Hydrogen and Oxygen make up Shopify’s recommended stack for headless commerce. The different parts of the system work together to make it faster and easier to build and deploy headless Shopify stores. Anchor to Architecture Architecture Three key parts of the Hydrogen stack work together to enable a unified developer experience: Technology What it does Hydrogen (App) A set of components, utilities, and design patterns that make it easier to work with Shopify APIs. Hydrogen projects are React Router apps that are preconfigured with Shopify-specific features and functionality. Hydrogen handles API client credentials, provides off-the-shelf components that are pre-wired for Shopify API data, and includes CLI tooling for local development, testing, and deployment. React Router (Framework) The open-source React framework that Hydrogen is built on top of. React Router handles routing, data fetching, server-side rendering, UI reactivity, and styling. Oxygen (Hosting) Shopify’s global serverless hosting platform, built for deploying Hydrogen storefronts at the edge. Oxygen handles deployment environments, environment variable management, caching, and integration with Shopify’s CDN. Developing each layer of this tech stack together means provides an end-to-end developer experience that reduces boilerplate code, improves productivity, and promotes optimal performance, accessibility, and SEO practices. Anchor to HydrogenHydrogen Anchor to Project structureProject structure Hydrogen projects are structured like typical React Router apps and you can configure them to your preferences. The following is the default Quickstart project structure: Hydrogen project structure 📂 hydrogen-quickstart/ ├── 📁 app/ │ ├── 📁 assets/ │ ├── 📁 components/ │ ├── 📁 graphql/ │ ├── 📁 lib/ │ ├── 📁 routes/ │ ├── 📁 styles/ │ ├── entry.client.jsx │ ├── entry.server.jsx │ └── root.jsx ├── 📁 public/ ├── CHANGELOG.md ├── README.md ├── customer-accountapi.generated.d.ts ├── env.d.ts ├── jsconfig.json ├── package.json ├── postcss.config.js ├── server.js ├── storefrontapi.generated.d.ts └── vite.config.js Anchor to Packages and dependencies Packages and dependencies Hydrogen bundles a set of dependencies that work together to enable end-to-end development and deployment: Package Description @shopify/hydrogen Main Hydrogen package. Contains components specific to React Router and utilities for interacting with Shopify APIs. Extends the framework-agnostic @shopify/hydrogen-react package. @shopify/hydrogen-cli CLI tool for working with Hydrogen projects. @shopify/mini-oxygen Local development server based on Oxygen. @shopify/remix-oxygen Remix adapter that enables Hydrogen to be served on Oxygen. Anchor to Hydrogen channelHydrogen channel The Hydrogen sales channel app needs to be installed on your Shopify store to enable the following features: A Hydrogen sales channel where you can publish product inventory. Oxygen hosting, to deploy your Hydrogen projects. Managing storefronts and deployment environments, including environment variable management. Access to deployment logs. Anchor to RoutesRoutes The standard format for product URLs is /products/:handle. If your storefront uses a different structure, then it’s recommended that you provide a server-side redirect (3XX) from the expected /products/:handle path to the product page. It’s also recommended that your storefront supports cart permalinks. View example implementation Anchor to React RouterReact Router React Router is the open-source React-based framework that Hydrogen is built on top of. Hydrogen projects are React Router apps with a set of preconfigured options, bundled with a collection of Shopify-optimized components and utilities. Hydrogen includes a custom React Router adapter that compiles your project for hosting on Oxygen. Tip Consider completing React Router’s 30-minute getting started tutorial for a solid foundation on the architecture and conventions of React Router apps. Anchor to Key React Router concepts Key React Router concepts Concept Details Nested routes React Router maps the nesting logic of app URLs to the nesting logic of components and data-loading. This allows all page data to load in parallel, reducing overall load times. Loaders React Router loaders are functions that load data so that it can be rendered server-side, which reduces the amount of JavaScript that’s sent to the client. In Hydrogen, loaders fetch data from Shopify APIs and third-party sources. Actions React Router actions are functions that accept web-standard form data from clients in order to update state, mutate data, or trigger side effects. SSR React Router apps default to server-side rendering (SSR), where their React components are rendered as HTML before being sent to the browser. Progressive enhancement Because React Router actions use web standard technology like HTML forms, they typically work without JavaScript, but can be enhanced with client-side JavaScript when it’s available. This, along with an SSR-first approach, means React Router apps typically deliver smaller bundle sizes that load faster. Anchor to Oxygen Oxygen Oxygen is Shopify’s global deployment platform that’s built for hosting Hydrogen storefronts at the edge. It provides multiple deployment environments, so you can preview every change before shipping it to production. Oxygen supports continuous deployment using GitHub, or you can configure your own custom CI/CD system. Enable access to Oxygen by installing the Hydrogen channel. Anchor to Supported plansSupported plans Oxygen is available at no extra charge on paid Shopify plans: Pause and build Basic Shopify Advanced Plus Oxygen isn’t available on Starter plans or development stores. Anchor to Technical specsTechnical specs Oxygen is a worker-based JavaScript runtime, based on Cloudflare’s open-source workerd library. It supports web standard APIs such as Fetch, Cache, Streams, Web Crypto, and more. Some Node.js APIs aren’t available. Check the Oxygen runtime details for a complete list. If you prefer, you can self-host Hydrogen. Anchor to LimitationsLimitations You can use Oxygen for hosting commerce storefronts. It’s subject to the Shopify Acceptable Use Policy. Misuse or abuse of Oxygen might lead to throttling, suspension, or termination. Workers: Must be 10 MB or less The startup time (the duration it takes for the worker to begin processing requests) must be 400 milliseconds or less. Must be named index.js. The optional source map file must be named index.js.map. Are limited to 30 seconds of CPU time per request Can consume 128 MB max of memory. Exceeding this limit could mean dropped requests. Are limited to 110 custom environment variables Outbound API requests must complete within 2 minutes Static assets, maximum file sizes: Images: 20 MB Video: 1 GB 3D models: 500 MB Other files: 20 MB Caution Ensure your requests go directly to Oxygen. Because proxies can conflict with Oxygen’s bot mitigation systems and cause SEO issues, Oxygen doesn’t support proxies in front of your Oxygen deployments. Anchor to Next stepsNext steps Fetch product data from Shopify
references: https://shopify.dev/docs/storefronts/headless/hydrogen/getting-started https://mock.shop/ Shopify’s official headless framework. (Alternatively, can add Shopify APIs to your existing tech stack.) Process: create new Hydrogen storefront link to Shopify store deploy it to Oxygen Requirements Node.js v16.20+ and npm v8.19+ Hydrogen channel Step 1: Create a new Hydrogen storefront In your terminal, create a new Hydrogen project using example data from Mock.shop: Terminal Copy 1 npm create @shopify/hydrogen@latest — –quickstart Note The --quickstart flag is shorthand for a set of recommended options for trying Hydrogen. You can drop it to see the available customizations. You’ll see a confirmation message with some details about your new project: Output 1 2 3 4 5 6 7 8 9 10 11 12 13 14 Shopify: Mock.shop Language: JavaScript Routes: • Home (/ & /:catchAll) • Page (/pages/:handle) • Cart (/cart/* & /discount/*) • Products (/products/:handle) • Collections (/collections & /collections/:handle) • Policies (/policies & /policies/:handle) • Blogs (/blogs/*) • Account (/account/*) • Search (/api/predictive-search & /search) • Robots (/robots.txt) • Sitemap (/sitemap.xml) Anchor to Step 2: Run the dev serverStep 2: Run the dev server After installation, open your new project and start the dev server: Terminal Copy 1 2 cd hydrogen-quickstart shopify hydrogen dev Once the dev server is running, open http://localhost:3000 in your browser and you’ll see Mock.shop inventory: Anchor to Step 3: Link your Hydrogen project to ShopifyStep 3: Link your Hydrogen project to Shopify By default, your Hydrogen project displays example products from Mock.shop. To show your own products, link your local project to Shopify, create a new storefront, and sync your environment variables. Link your Hydrogen project to Shopify: Terminal Copy 1 npx shopify hydrogen link Follow the prompts to log in to your Shopify account and create a new storefront: Output 1 2 3 4 5 6 7 ✓ my-shopify-store ? Select a Hydrogen storefront to link: ✓ Create a new storefront ? New storefront name: > hydrogen-quickstart Update your project’s environment variables: Terminal Copy 1 npx shopify hydrogen env pull Your terminal will show a diff like this: Output 1 2 3 4 5 6 7 – SESSION_SECRET=”foobar” – PUBLIC_STORE_DOMAIN=”mock.shop” + PUBLIC_STOREFRONT_ID=[ID] + PUBLIC_STOREFRONT_API_TOKEN=[TOKEN] + PRIVATE_STOREFRONT_API_TOKEN=[TOKEN] + PUBLIC_CUSTOMER_ACCOUNT_API_CLIENT_ID=[ID] + PUBLIC_CUSTOMER_ACCOUNT_API_URL=https://shopify.com/[ID] To confirm that the link works, run npm run dev and open http://localhost:3000. You’ll now see your storefront inventory in your browser: Anchor to Step 4: Deploy to OxygenStep 4: Deploy to Oxygen After your Hydrogen storefront is linked, you can deploy it to Oxygen hosting to make it publicly accessible: Deploy your project to Oxygen: Terminal Copy 1 npx shopify hydrogen deploy At the prompt to pick which environment to deploy to, select Preview. The Hydrogen CLI builds your storefront, creates a new Oxygen deployment, and returns a preview link in your terminal. Open the preview link in your browser see deployment URL: Anchor to Next stepsNext steps Congratulations! You’ve created a new Hydrogen storefront, connected it to Shopify, and made your first deployment to Oxygen. Hydrogen and Oxygen fundamentals Explore the key components of the Hydrogen and Oxygen stack and how they work together
