DOCSEARCHbyAlgolia
Submit Docs

Shopify Hydrogen

repository·main·Indexed 24 days ago

https://github.com/shopify/hydrogen

Shopify's headless commerce stack providing tools and utilities to build performant commerce applications. It is primarily designed for React Router but includes a portable React library. The documentation includes the Hydrogen Cookbook, a collection of reproducible recipes for the Hydrogen skeleton template, featuring a CLI for managing, validating, and applying recipes, as well as LLM prompts for AI-assisted coding.

Tokens
200.2K
Snippets
356
Records
698
Agent score
82%

What's inside Hydrogen

  2. Overview of Hydrogen packages

    main

    Hydrogen is a monorepo containing several specialized packages for building headless commerce applications:

    • @shopify/hydrogen: Opinionated tools and utilities designed for building commerce applications specifically with React Router.
    • @shopify/hydrogen-react: An unopinionated library of Shopify-specific commerce components, hooks, and utilities that can be used with other frameworks.
    • @shopify/cli-hydrogen: An extension for the Shopify CLI.
    • @shopify/create-hydrogen: The CLI tool used to generate new Hydrogen projects.
    • @shopify/hydrogen-codegen: A tool to automatically generate types for Storefront API and Customer Account API queries.
    • @shopify/mini-oxygen: A local runtime that simulates the Oxygen production environment for local development.

  3. Use @shopify/cli-hydrogen

    main
    @shopify/cli-hydrogen is the Hydrogen extension for the Shopify CLI. It provides tools, utilities, and examples for building commerce applications using Remix. You can use it to initialize new Hydrogen projects or manage existing ones via the Shopify CLI.

  4. Build a CMS using Shopify metaobjects in Hydrogen

    main

    This recipe demonstrates how to create a custom Content Management System (CMS) using Shopify metaobjects. It allows you to manage dynamic content sections (like Hero banners, Featured Products, or Store profiles) directly through the Shopify admin.

    Key capabilities include:

    • Dynamic Route Rendering: Content is rendered based on metaobject data.
    • Modular Components: Uses reusable React components that map to specific metaobject types.
    • Direct Editing: Includes an EditRoute component to provide direct links to the Shopify admin for content management in development mode.
    • Rich Text Support: Integrates with the Slate editor for rich text fields.

    Note: You must create the corresponding metaobject definitions in your Shopify admin before implementing this recipe. Each section component in the recipe has a one-to-one relationship with a specific metaobject definition.

  5. What is Hydrogen Codegen

    main

    Hydrogen Codegen is a codegen plugin and preset designed to generate TypeScript types from GraphQL queries into a .d.ts file. It wraps @shopify/graphql-codegen and provides specialized utilities for Hydrogen.

    Key characteristics:

    • Zero Runtime Overhead: It adds 0 bytes to your bundle as it only generates type definitions.
    • No Wrapper Required: It does not require specific function wrappers to work.
    • Type Safety: It enables type safety for GraphQL queries by allowing the GraphQL client to use TypeScript interfaces that are extended in the generated .d.ts file.

  6. What is the Hydrogen Cookbook and how do recipes work?

    main

    The Hydrogen Cookbook is a collection of reproducible recipes designed to be applied to the Hydrogen skeleton template.

    A recipe is a structured set of instructions that automates specific scenarios or use cases. Each recipe is organized into a folder containing:

    • recipe.yaml: A machine-readable definition of the entire recipe.
    • ingredients/: A directory of new files to be introduced to the skeleton template (copied as-is).
    • patches/: A directory of patches to be applied to existing files in the skeleton template. The mapping between files and patches is defined in recipe.yaml under the ingredients key.
    • README.md: A human-readable Markdown version of the recipe generated from recipe.yaml.

  7. Add language dynamic segments to routes

    main

    To implement path-based localization, you must add an optional language dynamic segment to your route files. This allows the router to match paths both with and without a locale prefix.

    Example Transformation:

    • Original: app/routes/_index.tsx
    • Localized: app/routes/($locale)._index.tsx

    This pattern should be applied to all application routes to ensure consistent localization across the site.

  8. Analyze bundle sizes with worker-bundle-analyzer

    main

    Hydrogen includes tools to analyze bundle sizes to help keep worker bundles small, which improves cold startup times.

    • Build Output: The build process generates client-bundle-analyzer.html and worker-bundle-analyzer.html files in the build output directory.
    • Constraints: Hydrogen will fail the build if your worker bundle exceeds 10 MB, as Oxygen only supports bundles under this limit.
    • Usage: Open the generated .html files in a browser to view an interactive analysis. The CLI output typically provides direct links to these files.

  9. Design a CMS architecture using Metaobjects

    main

    You can build a custom Content Management System (CMS) in Hydrogen by structuring metaobjects into a hierarchy of Routes and Sections:

    1. Route Metaobjects: Act as containers. A single Route metaobject holds one or many references to Section metaobjects.
    2. Section Metaobjects: Represent specific UI components (e.g., SectionHero, SectionFeaturedProducts). Each Section metaobject contains the specific fields (text, images, references) required to render that component.

    This allows merchants to reorder sections within a route or create entirely new pages by simply composing different metaobject entries in the Shopify Admin.

  10. Calculate subscription price adjustments

    main

    When a subscription plan is selected, the price may differ from the standard variant price. The Storefront API provides priceAdjustments which you must process manually in your UI.

    Supported adjustment types:

    • SellingPlanFixedAmountPriceAdjustment: Adds a specific amount to the base price.
    • SellingPlanFixedPriceAdjustment: Sets the price to a specific fixed amount.
    • SellingPlanPercentagePriceAdjustment: Applies a percentage discount to the base price.

    Always use the amount and currencyCode from the resulting calculation to render the final price using the <Money /> component.

  11. Configure development and production bundles

    main

    Hydrogen React provides separate development and production bundles. The development bundle includes extra warnings and messages to assist during development.

    Most modern bundlers or runtimes will automatically select the correct bundle based on the package.json#exports field. If your environment does not automatically select the correct bundle, you must configure your bundler or runtime to respect the development and production conditions.

    Note: If your bundler/runtime does not understand export conditions, it will default to the production bundle.

  12. Use LLM prompts from the Hydrogen Cookbook

    main
    Recipes in the cookbook are paired with LLM prompts. These prompts can be included in a Hydrogen project to enhance the AI-assisted coding experience by providing context-specific instructions related to the recipe being used. Prompts are located in the /cookbook/llms directory.