Forem: Emre MUTLU

Shopify Hydrogen Product Descriptions and SEO: Render Them in Initial HTML

Emre MUTLU — Mon, 04 May 2026 16:12:31 +0000

Shopify Hydrogen Product Descriptions and SEO: Render Them in Initial HTML

By Emre Mutlu, creator of the world's first English Shopify Hydrogen course on Udemy. May 3, 2026.

Published: May 3, 2026
Last updated: May 3, 2026
Reading time: 5 min

TL;DR

A practical Hydrogen SEO note on moving Shopify product descriptions out of client-only fetches and back into server-rendered product page HTML.

The storefront problem

A Shopify Hydrogen product page can look fine in the browser and still be weak in the initial HTML. That is exactly the kind of technical SEO issue that hides in plain sight: the Product Description accordion opens for users after JavaScript runs, but View Source does not contain the actual product description text.
For a product detail page, that is not a small detail. The description usually contains material, sizing, care, warranty, use case, brand language, and buying context. If that content is loaded only after hydration, the page is asking crawlers, AI systems, accessibility tools, and no-JavaScript users to wait for client-side behavior before they can understand the product.
The fix is not to remove the accordion. The fix is to make the accordion content server-rendered first, then let JavaScript enhance the interaction.

Why this matters for Hydrogen SEO

Google can render JavaScript, but that does not make client-only primary content a good default. Google's JavaScript SEO guidance still calls server-side rendering and pre-rendering useful because not every crawler behaves like a modern browser, and because JavaScript rendering can introduce delay or failure points.
On a Shopify Hydrogen product page, the safer rule is simple: if the content helps a shopper decide, it should be present in the initial HTML response.
That includes product title, price state, selected variant context, key product media, structured data, and the standard Shopify product description. The description should not depend on a client-only fetch unless it is genuinely secondary content.

The specific bug pattern

The pattern usually looks like this:

Layer	Broken behavior	Better behavior
Product route loader	Fetches product shell, variants, media, and commerce state	Also fetches standard product description or descriptionHtml
Description component	Fetches or receives content only after hydration	Receives description from server-loaded route data
Accordion UI	Content appears only after client JavaScript	Content exists in HTML; JavaScript only controls interaction
SEO verification	View Source has an empty description area	View Source contains real product description text

The important part is the ownership boundary. Product description is not an interactive widget. It is product content. It belongs in the route data.

The Shopify field to use

In this case, the description came from Shopify's standard product description field, not a metafield. That matters because it keeps content ownership where merchants already expect it: inside the Shopify product editor.
For Hydrogen storefronts using the Storefront API, the Product object exposes description data. Use plain description when text is enough, and descriptionHtml when the storefront needs Shopify's formatted HTML output.
A simplified query shape looks like this:

fragment ProductDescription on Product {
  id
  title
  description
  descriptionHtml
}

The exact query should live wherever the project already centralizes product fragments. Do not scatter a second product fetch into the accordion just to get the description. That creates a new failure mode and makes the page harder to reason about.

The implementation shape

The clean implementation is boring, which is usually a good sign.

Confirm the product route loader already queries the standard product description field.
If it does not, add description or descriptionHtml to the existing product fragment.
Pass the loaded value into the product page component tree.
Render it inside the Description accordion during SSR.
Keep the current accordion behavior for JavaScript-enabled users.
Remove any client-only fetch if it was the only source of description content.

A simplified React shape:

function ProductDescriptionAccordion({descriptionHtml}: {descriptionHtml?: string | null}) {
  if (!descriptionHtml) return null;
  return (
    <details className="product-accordion" open>
      <summary>Description</summary>
      <div className="product-description" dangerouslySetInnerHTML={{__html: descriptionHtml}} />
    </details>
  );
}

That example is intentionally small. In production, the exact HTML rendering should follow the project's existing sanitization or trusted Shopify HTML pattern. The SEO point is not the component API. The point is that the content is available to React during server render.

Accordion UX should not fight crawlability

Accordions are not the problem. Client-only content is the problem.
A product page can keep the same visual behavior and still be SEO-safe. The server can render the description into the HTML, and the client can decide whether the accordion starts open, closed, animated, or controlled by an existing disclosure component.
For crawlers and no-JavaScript users, the content exists. For shoppers, the UI stays familiar. That is the right tradeoff.

How I would verify it

I would not mark this kind of fix complete just because the page looks correct in Chrome.
The real checks are:

Open View Source on a product page and search for a unique sentence from the product description.
Disable JavaScript and reload the product page.
Confirm the Description content is still visible or accessible.
Confirm the accordion still behaves normally with JavaScript enabled.
Confirm no separate client fetch remains as the only source for description text.
Run TypeScript, lint, or the relevant Hydrogen build command.

That verification catches the difference between rendered DOM and initial HTML. SEO problems often live exactly in that gap.

Why this is a business issue, not just a technical cleanup

Product descriptions are commercial content. They explain why the product exists, what it is made of, how it should be used, and why it should be trusted.
If that content is missing from the initial HTML, the storefront is weaker than it looks. Search engines get less context. AI systems get less product detail. Accessibility and low-JavaScript environments become less reliable. The team also ends up debugging a problem that should have been solved at the data boundary.
For a growing Shopify brand, this is the quiet kind of Hydrogen debt: the storefront works, but the implementation makes important content harder to crawl, test, and maintain.

The practical lesson

In Hydrogen, not every missing SEO signal is a meta tag problem. Sometimes the issue is simpler: important product content is in the wrong rendering phase.
The fix is to move product description back into the product route loader and render it on the server. Then the accordion can remain an accordion. The page becomes easier for shoppers, crawlers, and future developers to trust.

FAQ

Should Shopify Hydrogen product descriptions be server-rendered?

Yes. If product descriptions matter for shoppers, SEO, or AI crawlers, they should be part of the initial product page HTML instead of appearing only after a client-side fetch.

Which Shopify field should power the product description?

Use Shopify's standard product description fields. The Storefront API exposes product description data, including descriptionHtml when formatted HTML is needed.

Can the description still live inside an accordion?

Yes. The accordion can stay. The important distinction is that the accordion content should already exist in the server-rendered HTML; JavaScript should only enhance the open and close behavior.

How do you verify the fix?

Open View Source and search for a unique sentence from the product description. Then disable JavaScript and confirm the same description remains visible or accessible on the product page.

{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "Should Shopify Hydrogen product descriptions be server-rendered?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Yes. If product descriptions matter for shoppers, SEO, or AI crawlers, they should be part of the initial product page HTML instead of appearing only after a client-side fetch."
      }
    },
    {
      "@type": "Question",
      "name": "Which Shopify field should power the product description?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Use Shopify's standard product description fields. The Storefront API exposes product description data, including descriptionHtml when formatted HTML is needed."
      }
    },
    {
      "@type": "Question",
      "name": "Can the description still live inside an accordion?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Yes. The accordion can stay. The important distinction is that the accordion content should already exist in the server-rendered HTML; JavaScript should only enhance the open and close behavior."
      }
    },
    {
      "@type": "Question",
      "name": "How do you verify the fix?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Open View Source and search for a unique sentence from the product description. Then disable JavaScript and confirm the same description remains visible or accessible on the product page."
      }
    }
  ]
}

Internal links

Shopify Hydrogen SEO guide Use this for the broader crawl, metadata, canonical, sitemap, and structured-data checklist.
Hydrogen homepage SSR case note A related production note about moving primary homepage data out of client-side effects.
Hydrogen performance, SEO, and UX optimization The service path for existing Hydrogen storefronts where crawlability, speed, or UX has drifted.
Work with Emre The direct route if your storefront needs senior Hydrogen implementation without agency layers.

External references

Google JavaScript SEO basics Google explains JavaScript rendering risks and notes that server-side or pre-rendering is still useful for users and crawlers.
Storefront API Product object Official Shopify reference for product fields, including description and descriptionHtml.
Hydrogen SEO documentation Official Shopify guidance for Hydrogen metadata, canonical URLs, JSON-LD, sitemap, and robots.txt.

Your Shopify store works, but every new feature takes 3x longer than last year? That's when I come in. If your Hydrogen product pages hide important catalog content behind client-side fetches, I can help move the right data back into SSR without breaking the storefront UX.

Shopify Hydrogen Metaobjects for Page-Specific Content Sections

Emre MUTLU — Wed, 29 Apr 2026 12:21:52 +0000

Shopify Hydrogen Metaobjects for Page-Specific Content Sections

By Emre Mutlu, creator of the world's first English Shopify Hydrogen course on Udemy. April 29, 2026.

Published: April 29, 2026
Last updated: April 29, 2026
Reading time: 5 min

TL;DR

A practical production note on using Shopify metaobjects to make a Hydrogen showroom appointment section editable per page without turning content changes into code changes.

A recent Bayam Jewelry task was simple on the surface: add a showroom appointment section near the bottom of the homepage. The important part was not the section itself. The important part was making the content editable per page without hardcoding a different component for every route.

The section needed a consistent frontend shape, but the content would later differ across a small set of high-intent pages:

Homepage
Men's
Women's
Diamonds
Watches

The product and collection templates already had their own appointment area, so those could stay shared. The job was to give the main landing pages a more flexible content model while keeping the storefront maintainable.

The storefront problem

Luxury ecommerce pages often look similar in structure but different in intent. A homepage showroom section might introduce the brand broadly. A watches page might lean into consultation, authentication, and appointment-led purchase confidence. A diamonds page might need language around guidance, selection, and showroom trust.

If all of that copy is hardcoded, every small content change becomes a developer ticket. If every page gets a custom component, the codebase gets noisy. If the content is pushed into a generic CMS model without a clear route mapping, the storefront becomes flexible in the wrong way.

The clean middle path is a structured Shopify metaobject.

The metaobject model

For this feature, the useful shape was small and deliberate:

Field	Purpose
Page context	Identifies where the entry should render, such as homepage, mens, womens, diamonds, or watches
Heading	The main section headline
Description	Supporting body copy below the heading
Image	Desktop image for the section
Mobile image	Optional mobile-specific image when the crop needs to change

This is exactly where metaobjects work well. Shopify describes metaobjects as reusable custom data structures with fields defined by a metaobject definition. That makes them a better fit than a loose collection of one-off metafields when the content belongs together as one structured block.

Why not hardcode it?

Hardcoding would have been faster for the first version. It would also create the same problem again the next time the team wants different copy for watches or diamonds.

The better question is not "can I build this section quickly?" It is "who should own the next content edit?"

For a section like this, the answer should usually be the merchant or ecommerce team. They should be able to update the heading, description, and image in Shopify Admin without asking a developer to change JSX.

Route-specific content without route-specific components

The frontend should stay boring. It should resolve the current page context, fetch the matching metaobject entry, and render the same section component with different content.

A simplified version of the logic looks like this:

type ShowroomAppointmentEntry = {
  pageContext: 'homepage' | 'mens' | 'womens' | 'diamonds' | 'watches';
  heading: string;
  description: string;
  image: string;
  mobileImage?: string;
};
function getShowroomPageContext(pathname: string) {
  if (pathname === '/') return 'homepage';
  if (pathname === '/mens') return 'mens';
  if (pathname === '/womens') return 'womens';
  if (pathname === '/diamonds') return 'diamonds';
  if (pathname === '/watches') return 'watches';
  return null;
}

The important idea is the fallback. Not every page needs a custom entry. If a page context does not match one of the editable landing pages, the storefront can keep using the existing shared collection or product appointment section.

That avoids unnecessary content sprawl.

Storefront API shape

In a Hydrogen storefront, the content can be queried through the Storefront API once the metaobject definition is accessible to the storefront. The exact query depends on the definition type and field keys, but the pattern is straightforward: fetch the entries for the metaobject type, find the entry whose page context matches the current route, and pass the fields into the component.

A simplified query shape looks like this:

query ShowroomAppointmentSections {
  metaobjects(type: "showroom_appointment_section", first: 20) {
    nodes {
      handle
      fields {
        key
        value
        reference {
          ... on MediaImage {
            image {
              url
              altText
              width
              height
            }
          }
        }
      }
    }
  }
}

The production details matter: normalize field keys, keep image handling predictable, and do not let a missing entry break the page. A missing metaobject entry should degrade to the default section, not to a broken landing page.

The merchant benefit

The outcome is not "we used metaobjects." That is implementation detail.

The merchant-facing outcome is better:

The homepage can have showroom copy that fits the broader brand story.
Men's, women's, diamonds, and watches pages can evolve independently.
The ecommerce team can edit heading, description, and imagery in Shopify Admin.
Product and collection pages can keep their existing shared behavior.
The frontend avoids five separate hardcoded section variants.

This is the kind of Hydrogen work that looks small but prevents future friction. The store gets more content flexibility without becoming more fragile.

The SEO angle

Metaobjects do not create SEO value by themselves. The value comes from rendering the selected content server-side so the route-specific heading and description exist in the initial HTML.

That matters for custom storefronts. If important content is only injected after hydration, crawlers and social parsers may not see the same page a shopper sees. For a showroom appointment section, the content is not the entire SEO strategy, but it supports route relevance when it is rendered cleanly.

The rule is simple: use metaobjects for merchant-editable structure, but still render the final content as real HTML.

When I would use this pattern again

This pattern is useful when a Shopify Hydrogen storefront needs repeated sections with controlled variation:

Appointment or consultation blocks
Editorial landing-page modules
Category-specific trust sections
Size guide or care-guide callouts
Storefront banners that differ by major page type
Brand storytelling blocks managed in Shopify Admin

I would not use it for every small string on the site. Too much content modeling creates a CMS maze. The right use case is a section that has a stable frontend layout and a clear business reason to vary by page.

The practical lesson

The best Hydrogen implementations do not move everything into code, and they do not move everything into content models. They draw a boundary.

Code should own the system: layout, data loading, fallback behavior, performance, and accessibility.

Shopify Admin should own the content that the merchant reasonably needs to change: heading, description, image, and page-specific messaging.

That boundary is what keeps a custom storefront maintainable after launch.

FAQ

When should a Shopify Hydrogen section use metaobjects?

Use metaobjects when the section has a repeatable structure but page-specific content, such as a heading, description, and image that merchants need to edit without code changes.

Are metaobjects better than hardcoded page content?

They are better when the content will change by page or campaign. Hardcoded content is fine for stable UI copy, but metaobjects are safer when merchandising, brand, or marketing teams need ownership.

Should every product and collection page get its own metaobject entry?

Not by default. A smaller set of page-context entries is easier to maintain. Product and collection defaults can stay shared unless there is a real business reason to personalize them.

Can metaobject-driven sections help SEO?

Yes, if the content is rendered server-side as part of the initial HTML. The SEO value comes from crawlable, route-specific content, not from the metaobject itself.

{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "When should a Shopify Hydrogen section use metaobjects?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Use metaobjects when the section has a repeatable structure but page-specific content, such as a heading, description, and image that merchants need to edit without code changes."
      }
    },
    {
      "@type": "Question",
      "name": "Are metaobjects better than hardcoded page content?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "They are better when the content will change by page or campaign. Hardcoded content is fine for stable UI copy, but metaobjects are safer when merchandising, brand, or marketing teams need ownership."
      }
    },
    {
      "@type": "Question",
      "name": "Should every product and collection page get its own metaobject entry?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Not by default. A smaller set of page-context entries is easier to maintain. Product and collection defaults can stay shared unless there is a real business reason to personalize them."
      }
    },
    {
      "@type": "Question",
      "name": "Can metaobject-driven sections help SEO?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Yes, if the content is rendered server-side as part of the initial HTML. The SEO value comes from crawlable, route-specific content, not from the metaobject itself."
      }
    }
  ]
}

Internal links

Shopify Hydrogen SEO guide Use this when page-specific content needs to stay crawlable, canonical, and structured.
Shopify Hydrogen services See the audit, migration, build, optimization, and support paths for Hydrogen storefronts.
Bayam Jewelry case study The broader context for luxury catalog and showroom-led Hydrogen storefront work.
Work with Emre The direct route if your storefront needs senior Hydrogen implementation without agency layers.

External references

Shopify metaobjects overview Official Shopify documentation explaining metaobject definitions, entries, fields, and storefront access.
Storefront API metaobjects query Official Storefront API reference for querying active metaobject entries by type.
Storefront API Metaobject object Official object reference for metaobject fields, handles, IDs, and updated timestamps.

Your Shopify store works, but every new feature takes 3x longer than last year? That's when I come in. If your Hydrogen storefront needs merchant-editable sections without turning every update into a developer ticket, I can help you model the content cleanly and keep the frontend stable.

Shopify Hydrogen Variant URLs and SEO: Fix Variant Selection Fallback Bugs

Emre MUTLU — Mon, 27 Apr 2026 09:43:00 +0000

Shopify Hydrogen Variant URLs and SEO: Fix Variant Selection Fallback Bugs

By Emre Mutlu, creator of the world's first English Shopify Hydrogen course on Udemy. April 25, 2026.

Published: April 25, 2026
Last updated: April 25, 2026
Reading time: 14 min

TL;DR

Shopify Hydrogen variant fallback bugs happen when the resolver treats the option a shopper clicked as a preference instead of a rule. The fix is to lock the clicked option first, then preserve stable variant URLs, UX, analytics, and SEO consistency.

Shopify Hydrogen gives you full control over the product page. That control is exactly why growing Shopify brands use it when a theme starts to feel too rigid. But the same freedom also means the small details are now your responsibility.

Variant selection is one of those details.

A simple product with one option is easy. A product with Width, Length, Metal, Size, Color, Finish, or Bundle Type is different. The storefront has to decide what happens when the exact combination a shopper requested is unavailable. If that decision is wrong, the shopper clicks one option and the page quietly sends them somewhere else.

That is not just a developer annoyance. It is a trust problem.

What is Shopify Hydrogen variant selection?

In Shopify Hydrogen, product options are usually rendered as custom React components. A shopper clicks an option, the selected values are reflected in the URL, and the page resolves those values to a product variant from Shopify's Storefront API.

A URL might look like this:

?Width=9mm&Length=18%22&Metal=14K

That URL-driven model is useful. It makes product states shareable. It lets the back button behave naturally. It gives analytics and QA a clearer picture of what a shopper selected. It also helps avoid a product page that only works as hidden client-side state.

But there is a catch: when the selected combination is out of stock or does not exist, the storefront has to choose a fallback variant. That fallback logic decides whether the product page feels intelligent or broken.

Modern variant API: getProductOptions and getAdjacentAndFirstAvailableVariants

There is one important freshness note for this topic: Shopify deprecated VariantSelector in the Hydrogen April 2025 release. The old component is still useful as historical context, but new Hydrogen product pages should be built around the modern product option flow.

The current pattern starts with Storefront API fields such as encodedVariantExistence, encodedVariantAvailability, selectedOrFirstAvailableVariant, adjacentVariants, and option values with firstSelectableVariant. Hydrogen then uses getProductOptions to build the option matrix from that product data. In product routes that need nearest-variant behavior, the migration notes point the Product component toward getAdjacentAndFirstAvailableVariants and explicit URL parameter handling.

That changes the plumbing, not the rule.

Whether your storefront previously used VariantSelector, a custom resolver, or the newer getProductOptions flow, the clicked option still needs to be preserved first. If the shopper clicks Width=9mm, the fallback logic should never send them back to Width=2mm just because another old option matches better.

The modern mental model is: build the product option matrix from Shopify data, keep selected options in the URL, use adjacent variant data for availability, and apply custom scope-first logic only where the default product option behavior does not match the buying journey.

The symptom: the shopper clicks one option, but the page keeps another

Here is the real pattern that causes trouble.

A shopper is on Width=2mm and Length=18 inches. They click Width=9mm.

The expected behavior is simple: keep Width=9mm, then find the nearest valid length for that width. If Length=18 inches is not available for 9mm, maybe the right fallback is Width=9mm and Length=20 inches.

The broken behavior is more subtle: the page navigates back to Width=2mm and Length=18 inches, because that old combination matched more of the previous selection.

To the shopper, this feels like the option button did not work. They clicked 9mm, but the product page refused to stay on 9mm.

Here is a small variant matrix that makes the problem easier to see.

Width	Length	Available
2mm	18 inches	Yes
2mm	20 inches	Yes
9mm	18 inches	No
9mm	20 inches	Yes
9mm	22 inches	Yes

User action	Bad fallback	Good fallback
Clicks Width=9mm from 2mm / 18 inches	2mm / 18 inches	9mm / 20 inches

The bad fallback optimizes for the old URL state. The good fallback preserves the shopper's new intent, then chooses the nearest available length inside that selected width.

The root cause: scoring all variants globally

The usual cause is a resolver that scores every variant in the product and picks the one with the highest score.

For example, the resolver might count how many currently selected options a candidate variant matches. A variant that matches the old width and old length can score higher than a variant that preserves the newly clicked width but needs a different length.

That is a priority inversion.

The option the shopper just clicked should not be one vote in a scoring system. It should be a hard rule.

If the shopper clicks Width=9mm, the resolver must first discard every variant that is not Width=9mm. Only after that should it ask which remaining variant is the best available fallback.

The invariant: the clicked option must survive

The strongest rule for Shopify Hydrogen variant fallback is this:

The returned variant must always contain the option the shopper explicitly clicked.

If they click Width=9mm, the final URL can change Length=18 inches to Length=20 inches. It can change an unavailable finish to the closest available finish. It can choose a nearby numeric value. But it must not return to Width=2mm.

That invariant protects shopper intent.

It also makes the code easier to reason about. Instead of asking, “Which variant is globally best?” the resolver asks, “Inside the option the shopper chose, which available variant is closest?”

That second question is much safer.

How a safer Shopify Hydrogen resolver should work

A good fallback resolver has three steps.

Scope candidates by the clicked option.

If the shopper clicked Width=9mm, filter the variant list to only variants where selected options include Width=9mm. If there are no variants in that scope, return no fallback rather than pretending another width is acceptable.

Try the exact match inside that scope.

If the current URL plus the clicked option creates an available variant, use it. This is the ideal path. The shopper gets exactly what they asked for, and the URL stays intuitive.

Find the nearest available variant inside the scope.

If the exact combination is not available, score only the available variants that still preserve the clicked option. For all other options, prefer exact matches first. If the values are numeric, use proximity.

That means Length=20 inches should beat Length=45 inches when the shopper was trying to stay near Length=18 inches. For sizes like 30mm, 45mm, or 18 inches, parsing the numeric part gives the resolver a useful fallback signal.

A small tie-break can also prefer the next higher value over the next lower value. In ecommerce, especially for dimensions, that often feels more natural than dropping below what the shopper selected.

TypeScript example: scope-first Hydrogen variant fallback

The exact implementation depends on your route, generated Storefront API types, and product option UI. But the resolver shape below captures the important invariant: scope by the clicked option before scoring anything else.

type SelectedOption = {
  name: string;
  value: string;
};

type Variant = {
  id: string;
  availableForSale: boolean;
  selectedOptions: SelectedOption[];
};

function hasOption(variant: Variant, option: SelectedOption) {
  return variant.selectedOptions.some(
    (item) => item.name === option.name && item.value === option.value,
  );
}

function numericValue(value: string) {
  const parsed = Number.parseFloat(value);
  return Number.isNaN(parsed) ? null : parsed;
}

function scoreVariant(variant: Variant, selectedOptions: SelectedOption[]) {
  return selectedOptions.reduce((score, option) => {
    const candidate = variant.selectedOptions.find(
      (item) => item.name === option.name,
    );

    if (!candidate) return score;
    if (candidate.value === option.value) return score + 10;

    const currentNumber = numericValue(option.value);
    const candidateNumber = numericValue(candidate.value);

    if (currentNumber === null || candidateNumber === null) return score;

    const diff = Math.abs(candidateNumber - currentNumber);
    const directionBonus = candidateNumber >= currentNumber ? 0.1 : 0;
    return score + Math.max(0, 5 - diff * 0.1) + directionBonus;
  }, 0);
}

function resolveFallbackVariant({
  variants,
  clickedOption,
  selectedOptions,
}: {
  variants: Variant[];
  clickedOption: SelectedOption;
  selectedOptions: SelectedOption[];
}) {
  const scopedVariants = variants.filter((variant) =>
    hasOption(variant, clickedOption),
  );

  if (!scopedVariants.length) return null;

  const exactMatch = scopedVariants.find(
    (variant) =>
      variant.availableForSale &&
      selectedOptions.every((option) => hasOption(variant, option)),
  );

  if (exactMatch) return exactMatch;

  return (
    scopedVariants
      .filter((variant) => variant.availableForSale)
      .sort(
        (a, b) =>
          scoreVariant(b, selectedOptions) - scoreVariant(a, selectedOptions),
      )[0] ?? null
  );
}

In a modern Hydrogen product page, this is not a replacement for getProductOptions. Think of it as the custom fallback rule you apply when your product experience needs stricter behavior than generic option navigation. The utility gives you the option matrix; this resolver protects shopper intent when a selected combination is missing or out of stock.

How to handle out-of-stock variants on page load

There is a related problem when a shopper lands directly on an out-of-stock variant URL.

Maybe Google, an ad, or a saved link sends them to Width=9mm and Length=18 inches, but that exact variant is out of stock. The page can either show the out-of-stock state or redirect to the nearest available variant.

If you auto-navigate, use the same discipline: preserve the primary product dimension.

For many products, the first option is the primary dimension. On a ring, bracelet, chain, or jewelry product, that might be Width. On apparel, it might be Size. On a technical product, it might be Model.

If the selected variant is out of stock, lock that primary option first. Then search for the nearest available variant among the other options.

The important part is that an out-of-stock fallback should not turn Width=9mm into Width=2mm just because 2mm has more inventory.

Inventory availability matters, but shopper intent matters first.

Why this matters for Shopify merchants

This kind of bug is easy to underestimate because it happens in edge cases. But edge cases on product pages are not small. They are moments where the shopper is actively choosing a configuration.

If the storefront changes their selection unexpectedly, three things happen.

The shopper loses confidence in the product interface.
Support questions increase because the selected option does not match what the shopper thought they chose.
Analytics becomes noisy because the URL says one thing, the click intent says another, and the final variant says something else.

For stores with complex catalogs, custom bundles, jewelry dimensions, product configurators, or B2B buying flows, variant logic is part of the buying experience. It is not just plumbing.

This is one of the reasons Hydrogen can be valuable. A theme can handle standard variant behavior well, but a custom storefront lets you build product logic around the real buying journey. The tradeoff is that the logic has to be built carefully.

Is this a Shopify Hydrogen bug?

Usually, no.

Hydrogen is a framework for building a custom storefront. It does not force one universal product option strategy because every catalog is different. A fashion store, jewelry store, parts catalog, and wholesale storefront do not all need the same fallback behavior.

The bug usually comes from implementation logic. The resolver searches all variants globally, gives points for matching current selected options, and forgets that the newly clicked option should be non-negotiable.

That is why the fix is architectural, not cosmetic.

Does this affect SEO?

Indirectly, yes. Variant fallback logic is not a magic SEO lever, but unstable variant URLs can create inconsistent product states for crawlers, analytics, QA, and shoppers.

How variant URL params affect crawl consistency

Hydrogen product option state often lives in search params. That is useful when the URL, selected UI state, product data, and rendered HTML agree. It becomes risky when a URL says Width=9mm but the rendered product quietly resolves to Width=2mm.

Google does not need every variant URL to be separately indexed. But if a variant URL is crawlable, it should render a coherent product state. The selected option, visible product content, add-to-cart variant ID, and structured data should not contradict each other.

When variant URLs should be indexable

Index variant URLs only when the variant meaningfully changes the search experience: different product imagery, materially different attributes, unique merchandising value, or a variant people actually search for. For simple color or size changes, indexing every URL can create thin or duplicate pages.

When to canonicalize to the base product

For most standard products, the safer default is to canonicalize option-param URLs back to the base product URL. Shopify's Hydrogen SEO docs show that canonical handling can be customized with getSeoMeta, including whether query params are appended. That decision should be deliberate, not accidental.

Product schema and selected variant consistency

If your page renders product JSON-LD, make sure the structured data reflects the same selected or primary product state the shopper sees. A fallback resolver that changes the selected variant without updating rendered state can create misleading product data.

How to test the SEO side

Test a few real variant URLs with JavaScript enabled and disabled. Confirm the canonical tag, visible selected options, add-to-cart variant, product schema, and final URL all tell the same story. Then use Google Search Console URL inspection after publishing to check what Google sees.

For Shopify Hydrogen SEO, the bigger lesson is consistency. Server-rendered product data, clean metadata, canonical decisions, JSON-LD, sitemap coverage, and stable variant URLs matter more than clever client-side behavior.

What I would test before shipping

Before shipping a multi-option Shopify Hydrogen product page, I would test these cases:

Clicking a width, size, or primary dimension never navigates away from that clicked value.
If the exact variant is unavailable, the fallback stays inside the clicked option group.
Numeric options choose the nearest available value, not the globally most similar old variant.
Out-of-stock direct URLs preserve the primary option before finding a replacement.
The browser URL, selected UI state, and Shopify variant ID all agree after navigation.
Back and forward navigation still restore the expected selected options.
Disabled or unavailable option states do not hide valid fallback paths.

The most important acceptance test is simple: after any option click, assert that the resolved variant still contains the clicked option name and value.

Common Shopify Hydrogen variant questions

How should Hydrogen product options be stored in the URL?

Use readable option names and values as search params when possible. That keeps product states easier to debug, share, and test. The exact format depends on your app, but the resolver should treat the URL as the source of selected option intent.

Should unavailable options be disabled?

Sometimes. But disabling every unavailable combination can make complex products feel dead. A better experience is often to allow the click, then guide the shopper to the nearest available valid combination while preserving the option they chose.

Should the fallback prefer available variants over exact matches?

Availability matters, but only after preserving intent. First lock the clicked option. Then prefer an exact available match inside that scope. Then choose the nearest available fallback.

Can this logic work for non-numeric options?

Yes, but proximity is easier with numeric values. For non-numeric values like Gold, Silver, Black, or Matte, exact matches and merchandising rules are usually more reliable than distance scoring.

When is custom Hydrogen variant logic worth it?

It is worth it when product discovery or configuration is part of the value of the store. If the catalog has complex dimensions, bundles, B2B rules, or merchandising paths that a theme cannot express cleanly, Hydrogen gives you room to build the right interaction.

If the catalog is simple and the theme already handles variants well, Hydrogen may be unnecessary complexity.

The practical lesson

Shopify Hydrogen is powerful because it lets you own the product experience. But ownership means the small rules matter.

A variant fallback resolver should not ask which variant is globally convenient. It should preserve the shopper's last explicit action, then find the closest available product state from there.

That one rule prevents a surprising class of bugs: never navigate away from the option the shopper just clicked.

For complex Shopify Hydrogen storefronts, that is the difference between a custom product page that feels premium and one that feels unpredictable.

FAQ

How should Shopify Hydrogen choose a fallback variant?

The safest pattern is to lock the option the shopper clicked first, then score only the available variants inside that locked set. The clicked option should be a hard constraint, not one preference among many.

Why do URL search params matter for Hydrogen product options?

Hydrogen product pages often store selected options in the URL, such as Width=9mm and Length=18. That makes variants shareable and crawlable, but it also means the resolver must update the URL without changing an option the shopper explicitly chose.

Should an out-of-stock Shopify Hydrogen variant redirect automatically?

It can, but only carefully. If the selected variant is out of stock, redirect to the nearest available variant while preserving the primary product dimension, such as Width, so the shopper does not feel the interface ignored their intent.

Is wrong variant fallback a Shopify Hydrogen bug?

Usually no. Hydrogen gives developers the flexibility to build custom product option logic. The bug normally lives in the storefront resolver when it searches all variants globally instead of scoping candidates to the clicked option.

What is the most important test for multi-option Hydrogen products?

Test that the returned variant always contains the option the shopper clicked. If they click Width=9mm, every fallback candidate and final URL must still contain Width=9mm.

Does this pattern still apply after VariantSelector was deprecated?

Yes. Hydrogen's modern product option flow uses getProductOptions and related adjacent variant data instead of relying on VariantSelector, but the storefront rule is the same: preserve the clicked option before choosing a fallback.

{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "How should Shopify Hydrogen choose a fallback variant?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "The safest pattern is to lock the option the shopper clicked first, then score only the available variants inside that locked set. The clicked option should be a hard constraint, not one preference among many."
      }
    },
    {
      "@type": "Question",
      "name": "Why do URL search params matter for Hydrogen product options?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Hydrogen product pages often store selected options in the URL, such as Width=9mm and Length=18. That makes variants shareable and crawlable, but it also means the resolver must update the URL without changing an option the shopper explicitly chose."
      }
    },
    {
      "@type": "Question",
      "name": "Should an out-of-stock Shopify Hydrogen variant redirect automatically?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "It can, but only carefully. If the selected variant is out of stock, redirect to the nearest available variant while preserving the primary product dimension, such as Width, so the shopper does not feel the interface ignored their intent."
      }
    },
    {
      "@type": "Question",
      "name": "Is wrong variant fallback a Shopify Hydrogen bug?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Usually no. Hydrogen gives developers the flexibility to build custom product option logic. The bug normally lives in the storefront resolver when it searches all variants globally instead of scoping candidates to the clicked option."
      }
    },
    {
      "@type": "Question",
      "name": "What is the most important test for multi-option Hydrogen products?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Test that the returned variant always contains the option the shopper clicked. If they click Width=9mm, every fallback candidate and final URL must still contain Width=9mm."
      }
    },
    {
      "@type": "Question",
      "name": "Does this pattern still apply after VariantSelector was deprecated?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Yes. Hydrogen's modern product option flow uses getProductOptions and related adjacent variant data instead of relying on VariantSelector, but the storefront rule is the same: preserve the clicked option before choosing a fallback."
      }
    }
  ]
}

Internal links

Shopify Hydrogen SEO guide Use this when product URL, canonical, JSON-LD, and crawl consistency questions need a broader framework.
Shopify Hydrogen cost Use this when the technical conversation needs a realistic budget range and timeline framing.
Production case studies See how Hydrogen decisions played out across real storefronts with different constraints.
Work with Emre The direct route if your store needs a specialist instead of another agency layer.
Should you use Hydrogen? A practical decision filter when the business case still needs checking.

External references

Hydrogen April 2025 update Official Hydrogen release notes covering the VariantSelector deprecation and getProductOptions migration path.
getProductOptions documentation Official Hydrogen utility reference for building modern product option matrices.
Hydrogen SEO documentation Official Shopify guidance for Hydrogen metadata, canonical URLs, JSON-LD, sitemap, and robots.txt.

Your Shopify store works, but every new feature takes 3x longer than last year? That's when I come in. If your Hydrogen product pages have edge cases like variant fallback, out-of-stock navigation, or option URLs that feel fragile, I can help you fix the logic without turning the storefront into a bigger rebuild than it needs to be.

How I Cut a Hydrogen Homepage From 5s to 2s

Emre MUTLU — Tue, 21 Apr 2026 18:27:06 +0000

How I Cut a Hydrogen Homepage From 5s to 2s

By Emre Mutlu, creator of the world's first English Shopify Hydrogen course on Udemy. April 21, 2026.

Published: April 21, 2026
Last updated: April 21, 2026
Reading time: 6 min

Article summary

I cut a Shopify Plus Hydrogen homepage from roughly 4 to 5 seconds to about 2 seconds by stopping the initial useEffect fetch, server-rendering only the first tab of each section, and lazy-loading the rest on interaction. The bigger win was not speed alone. It was getting product HTML back into the first response.

I cut a production Shopify Plus Hydrogen homepage from roughly 4 to 5 seconds to about 2 seconds by removing one bad assumption: that every tab on the page needed its product data on first load. It did not. Once I moved the first tab into the route loader and lazy-loaded the rest, both speed and SEO got cleaner.

Why the homepage was slow in the first place

The slowdown came from loading too much data too late. A single homepage section had 12 tabs with 8 products each, which meant 96 products per section before counting multiple sections. All of that was fetched client-side in useEffect, so the page hydrated first, then started the real work.

This was for a Shopify Plus jewelry brand I work with, a homepage with multiple horizontal product rails and filter tabs. From a React point of view, the code looked harmless. From a Hydrogen point of view, it was a footgun, especially if you have not internalized React's You Might Not Need an Effect guidance yet.

// Before, anti-pattern in Hydrogen
function HomepageSection() {
  const [products, setProducts] = useState([]);

  useEffect(() => {
    fetchAllTabsProducts().then(setProducts);
  }, []);

  return <Tabs products={products} />;
}

The practical result was obvious. The homepage took roughly 4 to 5 seconds to feel ready. The SEO problem was quieter. The initial HTML had no product listings at all, because product data only arrived after hydration.

What I changed, and why it worked

I changed the fetch strategy to match real user behavior. Only the first tab of each section is server-rendered with its 8 products. The rest of the tabs lazy-load on click. That cuts initial data weight, gets product HTML into the response, and stops the homepage from paying for tabs most users never open.

I moved the first-tab fetch into the route loader and removed the initial useEffect path entirely. The component now receives the first tab as props from the server response, and only requests other tabs after an actual interaction. If you want the official Hydrogen side of this pattern, Shopify's caching docs are the right reference for the cache layer.

// After, Hydrogen-native
export async function loader({context}) {
  const firstTabProducts = await context.storefront.query(FIRST_TAB_QUERY, {
    cache: context.storefront.CacheCustom(
      // Tuned to the product catalog's update frequency
    ),
  });

  return json({firstTabProducts});
}

function HomepageSection() {
  const {firstTabProducts} = useLoaderData();

  return <Tabs initialProducts={firstTabProducts} />;
}

That one change cut the homepage from roughly 4 to 5 seconds to about 2 seconds in observed behavior. I did not benchmark it with Lighthouse or WebPageTest, so I am not pretending this is a lab-grade performance study. It is a production engineering note. The page felt dramatically lighter because it stopped trying to fetch everything just in case.

The SSR bug that almost made this change look finished when it wasn’t

The first deploy still had an SSR hole. The in-house team tested the homepage with JavaScript disabled and found that the first-tab products were still missing from the initial HTML. That meant the SSR fix was not actually fully server-side yet, even though the page looked correct in a normal browser session.

The root cause was leftover client-only logic. The first tab had been conceptually moved to the loader, but one residual branch still routed its fetch through the old client path. So the UI worked, but the HTML response was still incomplete.

The fix was simple once the test exposed it. I made sure the first-tab data was fetched in the route loader and passed straight into the component as props, with no fallback path that depended on hydration. After that, the JS-disabled test showed product listings in the HTML exactly where they should be.

This is why I keep telling teams that it works in the browser is not a real SSR test. If the route matters for SEO, disable JavaScript once before you call it done. It is the fastest sanity check you can run.

The small UI cleanup that broke context after the performance fix

Performance changes often create pressure to compress the UI, and that can quietly remove meaning. In this case I stripped category prefixes from tab labels so long titles fit better inside horizontal rails. The result looked cleaner, but one section lost enough context that the shortened label became confusing.

A good example was the chain section. Titles like Diamond Chains and Gold Chains were shortened to make the tabs visually lighter. After deploy, the team noticed that under the Gold Chains section, the label just read Chains. It was shorter, but it also felt detached from the parent context.

The fix was to add a conditional guard rail. Prefix stripping stayed in place for titles where the parent section already carried the right context, but not in cases where shortening the label made the tab feel generic. That was a small change, but it mattered. Faster UI is not automatically clearer UI.

I mention this because performance work often gets discussed as if it is separate from interface language. It is not. Every time you compress data, text, or layout, you risk dropping context that the user still needed.

What I would tell another Hydrogen developer before they copy this pattern

If your first instinct is to preload every tab on a tabbed homepage, stop and check whether real users justify that cost. Most do not. They look at the first tab, some click the second, and very few make their way through all 12 tabs across multiple sections. Optimize for the common path, not the paranoid one.

If you are fetching primary route data in useEffect on a Hydrogen page, you are usually fighting the framework. Hydrogen gives you route loaders for a reason. Use the server for the part of the page that must exist on first load, then lazy-load the rest behind real user intent.

If you need more background before making that decision, my Should I Use It? page explains where Hydrogen is justified and where it is not. My cost breakdown is the practical version of the same conversation, and the case studies page shows the kind of stores where these tradeoffs actually appear.

The larger lesson is that this was not really a Hydrogen problem. It was a React habit problem. Teams coming from SPA-heavy or Next.js-heavy workflows reach for useEffect because it feels familiar. In Hydrogen, that habit gets expensive fast. You lose SSR, you lose HTML visibility, and you slow down the exact page that should be easiest to trust.

FAQ

Why was useEffect the wrong place for this homepage fetch?
Because it pushed primary page data to the client after hydration. That delayed the moment the homepage felt ready and removed product listings from the initial HTML, which is the wrong tradeoff for a category-heavy storefront.

What changed after moving the first tab to the route loader?
The first tab became part of the server-rendered response. That put real product HTML in the initial response, improved the ready state, and passed the simplest SSR check, loading the page with JavaScript disabled.

Should every tab be preloaded on a Hydrogen homepage?
Usually no. Most users interact with the first tab, some click the second, and very few open every tab in every section. Preloading everything is often an expensive guess that hurts the common path.

Where does intentional cache tuning fit in this pattern?
It matters when collection freshness and edge caching need to match catalog behavior. The bigger point is not one exact number. It is moving the first tab into the loader and caching the query deliberately instead of relying on a client-side effect.

FAQ

Why was useEffect the wrong place for this homepage fetch?

Because it pushed primary page data to the client after hydration. That delayed the moment the homepage felt ready and removed product listings from the initial HTML, which is the wrong tradeoff for a category-heavy storefront.

What changed after moving the first tab to the route loader?

The first tab became part of the server-rendered response. That put real product HTML in the initial response, improved the ready state, and passed the simplest SSR check, loading the page with JavaScript disabled.

Should every tab be preloaded on a Hydrogen homepage?

Usually no. Most users interact with the first tab, some click the second, and very few open every tab in every section. Preloading everything is often an expensive guess that hurts the common path.

Where does intentional cache tuning fit in this pattern?

It matters when collection freshness and edge caching need to match catalog behavior. The bigger point is not one exact number. It is moving the first tab into the loader and caching the query deliberately instead of relying on a client-side effect.

{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "Why was useEffect the wrong place for this homepage fetch?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Because it pushed primary page data to the client after hydration. That delayed the moment the homepage felt ready and removed product listings from the initial HTML, which is the wrong tradeoff for a category-heavy storefront."
      }
    },
    {
      "@type": "Question",
      "name": "What changed after moving the first tab to the route loader?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "The first tab became part of the server-rendered response. That put real product HTML in the initial response, improved the ready state, and passed the simplest SSR check, loading the page with JavaScript disabled."
      }
    },
    {
      "@type": "Question",
      "name": "Should every tab be preloaded on a Hydrogen homepage?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Usually no. Most users interact with the first tab, some click the second, and very few open every tab in every section. Preloading everything is often an expensive guess that hurts the common path."
      }
    },
    {
      "@type": "Question",
      "name": "Where does intentional cache tuning fit in this pattern?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "It matters when collection freshness and edge caching need to match catalog behavior. The bigger point is not one exact number. It is moving the first tab into the loader and caching the query deliberately instead of relying on a client-side effect."
      }
    }
  ]
}

Review Notes

Weakest part: The post still relies on observed production timing instead of a repeatable lab benchmark, so the performance claim is persuasive but not yet benchmark-grade.
Missing raw material: A real DevTools waterfall screenshot, Lighthouse diff, or the exact first-tab query would make the next version much stronger.
AI citation potential: 8/10

Your Shopify store works, but every new feature takes 3x longer than last year? That is when I come in. If your homepage, collection, or product pages are hitting the ceiling of what your current stack can deliver, I can help you see whether Hydrogen is the right move, and if it is, how to implement it without these traps.

[EN] Project Development Guide with React — Emre MUTLU

Emre MUTLU — Wed, 19 Apr 2023 13:23:45 +0000

[EN] Project Development Guide with React — Emre MUTLU

Hello,
This guide contains rules that must be followed when developing applications with React. This guide aims to ensure that the codes written by different people are compatible with each other and to produce higher quality codes with fewer errors. In other words, it is aimed that people working in a team coherently writing code.
Note: **Take everything here as an opinion, not an absolute. There’s more than one way to build software.

About the Author
For over two years, I’ve been developing projects with React. I learned the necessary information to enter this sector on the internet. That’s why I want to pay my debt to the community and contribute to the development of the community by sharing the knowledge I have gained on the internet.

“Knowledge grows as it is shared”

CONTENTS:

*WHAT TO KNOW BEFORE YOU START READING
*- Basic Javascript Information

Why Did I Choose to Use VSCode?
SOLID Principles

*WHAT TO DO
*- VSCode Settings

Basic Principles
Naming
Formatting

RECOMMENDED

Form Usage
VSCode Snippets
Leave it how you want to find it
Asking for Help
Starting with the Simple Things

*WHAT NOT TO DO
*- Avoid actions that will lead to loss of performance

Avoid the Use of “Magic String”
Avoid the Use of “Inline CSS”
Avoid Writing Long Code
Direct Object Intervention should be avoided
Incorrect State Use Should Be Avoided
Do You Need to Use Else?
Do You Need to Use Array.push()?
Avoid Props Drilling
Bonus :)

I WANT TO TAKE MY REACT KNOWLEDGE EVEN FURTHER
Last Word

THINGS TO KNOW BEFORE YOU START READING

There are too many technical terms in the text, so to explain them all, I added a link to the explanation for the subject mentioned in the technical terms. (Underlined phrases are clickable links.)

Basic Javascript Information

Be sure to learn the basic Javascript information described in this article: https://www.freecodecamp.org/news/top-javascript-concepts-to-know-before-learning-react/

Be sure to understand the following statement thoroughly.
“Everything is a component in React.”

Well, we use HTML tags (eg: …).

Actually, it is a React Component; we are using *JSX. We do not use *HTML. For an introduction to JSX, read: https://reactjs.org/docs/introducing-jsx.html

Note: This guide assumes you are using the functional component. Click to examine the differences between functional components and class components.

Note: This guide assumes you are using VSCode. If you use Webstorm or any other code editor, you can ignore the VSCode-related parts.

Why did I choose to use VSCode?
Because I love VSCode’s code snippets system, shortcuts, the repository of add-ons, and customizability.
You can find detailed information about **VSCode **at this address: https://code.visualstudio.com/docs/editor/whyvscode#:~:text=With%20support%20for%20hundreds%20of,navigate%20your%20code%20with%20ease.

SOLID Principles

If we apply the SOLID principles to REACT:
S = Single responsibility principle (SRP) => “Every function/module/component should do exactly one thing”

In the example below, user information and displaying the component are done in a component. This is a violation of the Single Responsibility Principle.

   const ActiveUsersList = () => {
      const [users, setUsers] = useState([])

      useEffect(() => {
        const loadUsers = async () => {  
          const response = await fetch('/some-api')
          const data = await response.json()
          setUsers(data)
        }
        loadUsers()
      }, [])

      const weekAgo = new Date();
      weekAgo.setDate(weekAgo.getDate() - 7);
      return (
        <ul>
          {users.filter(user => !user.isBanned && user.lastActivityAt >= weekAgo).map(user => 
            <li key={user.id}>
              <img src={user.avatarUrl} />
              <p>{user.fullName}</p>
              <small>{user.role}</small>
            </li>
          )}
        </ul>    
      )
    }

Instead of giving more than one responsibility to the component, we should split the duties into two different functions, as shown in the example below.

In the example below, user information access is assigned to the hook named useUser(). The responsibility of displaying the data (showing it in the interface) is given to the component called ActiveUsersList. This way, both functions have only one task.

` const useUsers = () => {
const [users, setUsers] = useState([])

  useEffect(() => {
    const loadUsers = async () => {  
      const response = await fetch('/some-api')
      const data = await response.json()
      setUsers(data)
    }
    loadUsers()
  }, [])

  return { users }
}
const ActiveUsersList = () => {
  const { users } = useUsers()

  const weekAgo = new Date()
  weekAgo.setDate(weekAgo.getDate() - 7)
  return (
    <ul>
      {users.filter(user => !user.isBanned && user.lastActivityAt >= weekAgo).map(user => 
        <li key={user.id}>
          <img src={user.avatarUrl} />
          <p>{user.fullName}</p>
          <small>{user.role}</small>
        </li>
      )}
    </ul>    
  )
}`

O = Open-closed principle (OCP) => “Software entities should be open for extension, but closed for modification”

In the example below, a Header component generates a new “Link” for each “pathname.” As the number of “paths” to be added to the application increases, the component will become quite complex. In other words, we must change the Header component for each new path we add.

const Header = () => {
      const { pathname } = useRouter()

      return (
        <header>
          <Logo />
          <Actions>
            {pathname === '/dashboard' && <Link to="/events/new">Create event</Link>}
            {pathname === '/' && <Link to="/dashboard">Go to dashboard</Link>}
          </Actions>
        </header>
      )
    }
    const HomePage = () => (
      <>
        <Header />
        <OtherHomeStuff />
      </>
    )
    const DashboardPage = () => (
      <>
        <Header />
        <OtherDashboardStuff />
      </>
    )

To prevent this situation, sending the links to the relevant page to the Header component within that page would be an excellent option.

const Header = ({ children }) => ( <header> <Logo /> <Actions> {children} </Actions> </header> ) const HomePage = () => ( <> <Header> <Link to="/dashboard">Go to dashboard</Link> </Header> <OtherHomeStuff /> </> ) const DashboardPage = () => ( <> <Header> <Link to="/events/new">Create event</Link> </Header> <OtherDashboardStuff /> </> )
L = Liskov substitution principle (LSP) => Objects in a program should be interchangeable with instances of their subtypes without changing the correctness of that program. This is a bit more related to classes. But if we try to adapt it to React, we can provide type control of the props passed to the component with PropTypes or TypeScript.

In the example below, both components are waiting for the same interface.

`interface CatFact {
  facts: string[];
  color: string;
}

const CatFactA = ({ facts, color }: CatFact) => {
  return (
    <>
      {facts.map((fact, index) => (
        <p style={{ color }}>
          Fact {index}: {fact}
        </p>
      ))}
    </>
  );
};

const CatFactB = ({ facts, color }: CatFact) => {
  return (
    <ul style={{ color }}>
      {facts.map((fact) => (
        <li>{fact}</li>
      ))}
    </ul>
  );
};

export default () => {
  const catFactData: CatFact = {
    facts: [
      "Cats make about 100 different sounds. Dogs make only about 10.",
      "I don't know anything about cats.",
      "Domestic cats spend about 70 percent of the day sleeping and 15 percent of the day grooming."
    ],
    color: "red"
  };
  const abTest = Math.floor(Math.random() * 2) + 1;
  return (
    <div>
      {abTest === 1 ? (
        <CatFactA {...catFactData} />
      ) : (
        <CatFactB {...catFactData} />
      )}
    </div>
  );
};`

*I *= Interface segregation principle (ISP) => “Clients should not depend upon interfaces that they don’t use.”

In the example below, the component named DisplayUser has retrieved the entire user object via props to access the user’s name. In other words, there may be many expressions in the user object that the component named DisplayUser is not interested in — for example, the user’s hair color, age, etc.

`const DisplayUser = (props) => {
  return (
    <div>
      <h1>Hello, {props.user.personalInfo.name}! </h1>
    </div>
  )
};

const App = () => {
  const user = {
    personalInfo: {
      name: "josh",
      age: 23
    },
    physicalFeatures: {
      hairColor: "blone",
      heightInC,: 175
    }
  }
  return (
    <div>
      <DisplayUser user={user} />
    </div>
  )
};`

Instead of passing the whole user object from the parent component to the child component named DisplayUser, we should pass only the object that concerns that component.

In the example below, since DisplayUser is only interested in the user’s name, it will be enough to pass it through the props.

`const DisplayUser = ({name}) => {
  return (
    <div>
      <h1>Hello, {name}! </h1>
    </div>
  )
};

const App = () => {
  const user = {
    personalInfo: {
      name: "josh",
      age: 23
    },
    physicalFeatures: {
      hairColor: "blone",
      heightInC,: 175
    }
  }
  return (
    <div>
      <DisplayUser name={user.personalInfo.name} />
    </div>
  )
};`

D = Dependency inversion principle (DIP) => “One should depend upon abstractions, not concretions”

In the example below, API is called directly inside the LoginForm component. However, this makes the LoginForm component directly dependent on API.

` import api from '~/common/api';

const LoginForm = () => {
  const [email, setEmail] = useState('');
  const [password, setPassword] = useState('');

  const handleSubmit = async (evt) => {
    evt.preventDefault()
    await api.login(email, password)
  }

  return (
    <form onSubmit={handleSubmit}>
      <input type="email" value={email} onChange={e => setEmail(e.target.value)} />
      <input type="password" value={password} onChange={e => setPassword(e.target.value)} />
      <button type="submit">Log in</button>
    </form>
  )
}`

To prevent this situation, we need to create a parent component that can connect the LoginForm component and the API object like glue and enable them to communicate.

type Props = {
      onSubmit: (email: string, password: string) => Promise<void>
    }
    const LoginForm = ({ onSubmit }: Props) => {
      const [email, setEmail] = useState('')
      const [password, setPassword] = useState('')
      const handleSubmit = async (evt) => {
        evt.preventDefault()
        await onSubmit(email, password)
      }
      return (
        <form onSubmit={handleSubmit}>
          <input type="email" value={email} onChange={e => setEmail(e.target.value)} />
          <input type="password" value={password} onChange={e => setPassword(e.target.value)} />
          <button type="submit">Log in</button>
        </form>
      )
    }

    import api from '~/common/api'
    const ConnectedLoginForm = () => {
      const handleSubmit = async (email, password) => {
        await api.login(email, password)
      }
      return (
        <LoginForm onSubmit={handleSubmit} />
      )
    }

** For example, you should not do data fetching in a component. The Component’s job is to render. It doesn’t need to know anything else. For this reason, we should do the data extraction in a different method and only pass the result of this data extraction to the Component.*

(Code examples above:

https://konstantinlebedev.com/solid-in-react/
https://medium.com/docler-engineering/applying-solid-to-react-ca6d1ff926a4 taken from their addresses).

WHAT TO DO

1. VSCode Settings
First of all, it is mandatory to use the “ESLint,” “Prettier,” and “GitLens” plugins for the VSCode application.
Why is it mandatory?

**ESLint **instantly warns you about your mistakes and prevents you from building incorrectly.
Prettier **allows your **codes to be formatted within the framework of your specific settings. (For example: Let a maximum of 120 characters be displayed on a line, more on the bottom line. Or end each variable with a semicolon after it is defined.) (We usually use Prettier at the time of saving.)
GitLens is a tool that allows you to do your Git operations from the VSCode interface. (You can see which line was added by who and with which commit message. In this way, you can better analyze the purpose of the written code.).
Install the “Emre MUTLU — Javascript — Extension Pack” add-on package if you wish.

The standard “Commit” format must be implemented on git. (For example, you can consider the commit messages system here and expand it by adding new rules for your projects. (Example: https://github.com/emremutlu08/react-best-practices/blob/main/common-commit-format/common-commit-format.md)

2. Basic Principles
*- *The principles of “DRY, KISS, and YAGNI” must be followed.
— DRY = Don’t Repeat Yourself: You should not have duplicated code.
— KISS = Keep It Super Simple (Orj: Keep It Simple, Stupid): Make your code simple
— YAGNI = You Ain’t Gonna Need It: You should not create features that it’s not really necessary.

It would be best if you put the “Single Responsibility” principle into practice.
All components must have an id. (This way, it will be easier for us to debug.) These IDs should not conflict with each other. Therefore, if the React version used in the project is less than 18, use the expression => id = Math.floor(Math.random() * 100 + 1) + ‘-’ + FILE_NAME, If it’s large, you can use the expression id = useId() + ‘-’ + FILE_NAME.
Everything has to be a component if it will use more than once.
All props used in the Component *FILE_NAME.propTypes = { … props should be added here } *- If mapping on a component array, adding a unique key value to the component in the most inclusive position is mandatory.
Limit nested folders to 3–4 levels to avoid complexity.

3. Naming

Proper and descriptive nomenclature is mandatory. (For example, instead of typing isModelOneOpen or shortening it to isModOnOp, you should name it isCreateModelOpen long and descriptively.) This way, you don’t have to add comments to explain it.
Constant names should be Snake Case (All Caps). (THANKS_FOR_READING)
File and folder names should be kebab-case. (thanks-for-reading)
Function names should be camelCase. (thanksForReading)
Component names should be PascalCase. (ThanksForReading)
Custom hook names must start with useSmt (Ex: useWindowSize)

4. Formatting

Write third-party (e.g., npm packages) imports at the top (in alphabetical order if possible). Write the in-app imports at the bottom.
Common “ESLint” and “Prettier” settings are mandatory for all new projects. (For example, you can use the settings available here: https://github.com/emremutlu08/emre-mutlu---javascript---extension-pack/tree/main/prettier-and-eslint-files)
Before committing your code, make sure that the formatting is correct.

Form Usage

To prevent frequent state changes, it will be helpful to use input fields within the
tag and to get the information in case of onSubmit. (React applications “render” happens “on every state change”. If this happens too often, it negatively affects application performance.) *Note: *You can also use the useMemo hook to avoid unnecessary rendering in different situations.

Note: If you have more than one button in a …, you must provide a type for every button element.

{}}>

// This is not invokes onSubmit
// This invokes onSubmit

VSCode Snippets

Create “VSCode snippets” (code snippets) for frequently used expressions. (This way, you avoid spending too much time on things that must be written repeatedly.) (You can use this tool to quickly generate snippets: https://snippet-generator.app/)

Leave it how you want to find it

Leave it the way you want to find it: Someone who came before you may have left the code messy, did copy-paste work, in short, left a poor quality code. You should fix the code whenever you find the opportunity so that you and the people who come after you will encounter more understandable codes.

### Asking for Help

**It is recommended to ask for help: **After you have done enough research and are sure that you cannot reach the result on your own, you should ask a teammate for help. Because you can get the answer quickly thanks to them saying a keyword you did not think of at that moment.

Starting with the Simple Things

It is recommended to start with simple tasks: Divide the task into small parts and always make simple tasks your priority. In this way, both “I could not progress in this process!” You get rid of the feeling, and you can tell your manager, “I have completed parts a, b, and c of this process, and only part X remains.”
If you start working from “X” to solve the difficult one, and your manager asks you, “what did you do” three days later, it wouldn’t be nice to say I’m still on “X,” right? :)

WHAT NOT TO DO

Avoid actions that will lead to loss of performance

Anything that will not be used on the current screen should not be called beforehand. (Especially at the beginning, it is necessary not to call everything and reduce the application’s performance.)

Avoid the Use of “Magic String”

It is necessary to avoid using strings that appear suddenly in the file called “Magic String”.
For example: (Type item.userTypeId === userTypeEnum.Admin **instead of **item.userTypeId === 2) should be written so that it is easy to read, and you don’t repeatedly look to see what Admin’s code was. (At the same time, if the Admin’s code changes, you will save yourself the hassle by changing it in one place.)
Example-2: (Use {EDIT_BUTTON_TEXT} *instead of *EDIT). (You can also use i18next, which provides convenient localization operations.)

Avoid the Use of “Inline CSS”

It is necessary to avoid using “Inline CSS” and proceed based on “Component” as much as possible. Because when there is a CSS change, changing it one by one from everywhere causes big problems.

Avoid Writing Long Code

Line length in a file should never exceed 500 lines. If you have written more than 300 lines of code, you should check what you wrote, divide it into meaningful parts / use it by separating it into methods. You have to import from different files.

Direct Object Intervention should be avoided

Do not interfere with an object as directly as possible. You must create a new copy of the object and modify it.

Incorrect State Use Should Be Avoided

Do not try to change the state information without using setState.

Do You Need to Use Else?

Avoid unnecessary if-else statements when you add the return statement in the if; the following statements do not work. So you don’t need to use else.

Do You Need to Use Array.push()?

Instead of array.push(), array restructuring, and appending should be done.
[…previousArray, { newObjectElement1: newObjectElementValue1 }]

Avoid Props Drilling

Avoid Props Drilling. (If your props reach more than two component levels, you are doing “Props Drilling”.)

Bonus :)

Please do not send requests in a for loop. :)

I WANT TO CARRY MY REACT KNOWLEDGE FURTHER

MUST READ:
**- **https://reactjs.org/docs/thinking-in-react.html

https://alexkondov.com/tao-of-react/
https://www.patterns.dev/
Learn the basics of Javascript very well.
https://reactpatterns.com/

Last Words:

We have come to the end of the guide, where I try to convey my experiences with React. I hope you have gained helpful information for yourself and your team in this article.
If you want to give **helpful **feedback on this guide, you can reach me on LinkedIn.

—
I want to thank all my friends who helped me develop this guide with their feedback. :)
—

I’m thinking of collecting the guide you read in a git repo under “React Best Practices” and sharing it on Github.
If you want to support me in this work and contribute to the development of the React ecosystem, you can give a star to the Github repo.

GitHub Repo: https://github.com/emremutlu08/react-best-practices

You can join my LinkedIn network with +26,000 followers to follow my daily posts about React and JavaScript: https://www.linkedin.com/in/emremutlujs/

Resources and Examples:

Writer:

Emre MUTLU — Linkedin

Supporters with their Feedback:

Ahmet Emre BAŞAKÇIOĞLU — Linkedin
Melike ŞANLI ARSLAN — Linkedin — Medium
Ezgi BIÇAK — Linkedin — Medium
Ercan AKALAR — Linkedin

*Translators: *

Emre MUTLU — Linkedin
Seha ÖZBEK — Linkedin