Metadata duplication during hydration with generateMetadata in Next.js 15 - specific to product pages using next js 15 medusa v2 starter template

[Bigpapabiggie69]

Summary

Metadata duplication during hydration with generateMetadata in Next.js 15 - specific to product pages

Problem

Metadata tags are being duplicated during client-side hydration in Next.js 15, but only on product pages. The server-side rendered HTML is clean with no duplication, but after hydration, duplicate metadata tags appear in the DOM. This does NOT happen on other pages (home, category, collection, blog pages).

Environment

• Next.js version: 15.5.3
• Browser: Firefox, brave, google chrome
• Operating System: Ubuntu x64

Steps to Reproduce

1. Create a product page with generateMetadata() function
2. Navigate to the page
3. Wait for hydration to complete
4. Inspect the DOM - duplicate metadata tags will appear
5. Refresh the page - server-side HTML is clean (no duplication)

Code Examples

Product Page (Has Duplication Issue)

// src/app/(main)/products/[handle]/page.tsx
export async function generateMetadata({ params }: Props): Promise<Metadata> {
  console.log('[generateMetadata] Called for product page')
  const { countryCode, handle } = await params
  
  try {
    const result = await getProduct(countryCode, handle)
    
    if (!result?.product) {
      return {
        title: "Product Not Found",
        description: "The requested product could not be found.",
      }
    }

    const { product } = result
    
    // Test with simplified metadata like category page
    return generateCategoryMetadata({
      title: product.title,
      description: product.description || `Shop ${product.title} at Example Store. Premium products with delivery available.`,
      keywords: product.tags?.map(tag => tag.value) || [],
      canonical: `/products/${product.handle}`,
      ogImage: product.images?.[0]?.url,
    })
  } catch (error) {
    console.error("Error generating product metadata:", error)
    return {
      title: "Product",
      description: "Premium products at Example Store.",
    }
  }
}

Category Page (Works Correctly)

// src/app/(main)/categories/[...category]/page.tsx
export async function generateMetadata(props: Props): Promise<Metadata> {
  const params = await props.params
  try {
    const productCategory = await getCategoryByHandle(params.category)
    
    // ... metadata processing logic ...
    
    return generateCategoryMetadata({
      title: baseTitle,
      description,
      keywords: allKeywords ? allKeywords.split(', ') : generateKeywords('category', { name: baseTitle }),
      canonical: url,
      ogImage: finalOgImage,
    })
  } catch (error) {
    notFound()
  }
}

Home Page (Works Correctly)

// src/app/(main)/page.tsx
export async function generateMetadata(): Promise<Metadata> {
  const title = "Example Products, Items & Services"
  const description =
    "Shop high-quality products, items and services. Premium options, safe and low-maintenance. Delivery available."

  return {
    title: title, // Let the template handle the formatting
    description,
    keywords: [
      "example products",
      "example items",
      "example services",
      "premium products",
      "high quality",
      "safe products",
      "indoor items",
      "outdoor items",
      "low maintenance",
    ],
    alternates: { canonical: `/` },
    openGraph: {
      // Let Next.js fall back to top-level title and description
      url: `/`,
      images: ["/opengraph-image.jpg"],
      siteName: "Example Store",
      type: "website",
    },
    twitter: {
      card: "summary_large_image",
      images: ["/twitter-image.jpg"],
    },
  }
}

Metadata Generator Functions

generateCategoryMetadata (Works Correctly)

export function generateCategoryMetadata(config: BaseMetadataConfig): Metadata {
  const {
    title,
    description,
    keywords = [],
    canonical,
    ogImage,
    noIndex = false
  } = config

  const baseUrl = process.env.NEXT_PUBLIC_BASE_URL || "http://localhost:3000"
  const canonicalUrl = canonical ? `${baseUrl}${canonical}` : undefined

  return {
    title: title, // Let the template add "| Example Store"
    description,
    keywords: keywords.join(", "),
    // Use alternates.canonical for proper canonical link tag
    alternates: canonicalUrl ? { canonical: canonicalUrl } : undefined,
    robots: {
      index: !noIndex,
      follow: !noIndex,
      googleBot: {
        index: !noIndex,
        follow: !noIndex,
        "max-video-preview": -1,
        "max-image-preview": "large",
        "max-snippet": -1,
      },
    },
    openGraph: {
      title: title, // Let the template add "| Example Store"
      description,
      url: canonicalUrl,
      images: ogImage ? [{
        url: ogImage,
        width: 1200,
        height: 630,
        alt: title,
      }] : undefined,
      type: "website",
      siteName: "Example Store",
      locale: "en_GB",
    },
    twitter: {
      card: "summary_large_image",
      title: title, // Let the template add "| Example Store"
      description,
      images: ogImage ? [ogImage] : undefined,
    },
  }
}

generateProductMetadata (Causes Duplication)

export function generateProductMetadata(config: ProductMetadataConfig): Metadata {
  const {
    title,
    description,
    keywords = [],
    canonical,
    ogImage,
    noIndex = false,
    price,
    availability = "in stock",
    brand = "Example Store",
    category = "Example Products",
    images = [],
    structuredData
  } = config

  const baseUrl = process.env.NEXT_PUBLIC_BASE_URL || "http://localhost:3000"
  const canonicalUrl = canonical ? `${baseUrl}${canonical}` : undefined

  return {
    title: title, // Let the template add "| Example Store"
    description,
    keywords: keywords.join(", "),
    // Use alternates.canonical for proper canonical link tag
    alternates: canonicalUrl ? { canonical: canonicalUrl } : undefined,
    robots: {
      index: !noIndex,
      follow: !noIndex,
      googleBot: {
        index: !noIndex,
        follow: !noIndex,
        "max-video-preview": -1,
        "max-image-preview": "large",
        "max-snippet": -1,
      },
    },
    openGraph: {
      title: title, // Let the template add "| Example Store"
      description,
      url: canonicalUrl,
      images: images.length > 0 ? [{
        url: images[0], // Only use first image to prevent duplication
        width: 1200,
        height: 630,
        alt: title,
      }] : ogImage ? [{
        url: ogImage,
        width: 1200,
        height: 630,
        alt: title,
      }] : undefined,
      type: "website",
      siteName: "Example Store",
      locale: "en_GB",
    },
    twitter: {
      card: "summary_large_image",
      title: title, // Let the template add "| Example Store"
      description,
      images: images.length > 0 ? [images[0]] : ogImage ? [ogImage] : undefined, // Only use first image
    },
  }
}

Interface Definitions

export interface BaseMetadataConfig {
  title: string
  description: string
  keywords?: string[]
  canonical?: string
  ogImage?: string
  noIndex?: boolean
  structuredData?: any
}

export interface ProductMetadataConfig extends BaseMetadataConfig {
  price?: string
  availability?: string
  brand?: string
  category?: string
  images?: string[]
}

Expected vs Actual Behavior

Behavior	Status
Server-side HTML should be clean (no duplication)	✅ Working
Client-side hydration should maintain clean metadata	❌ Failing
All pages should behave consistently	❌ Only product pages fail

Additional Notes

• The issue persists even when using generateCategoryMetadata() instead of generateProductMetadata() on product pages
• The issue persists even with inline metadata (no metadata generator function)
• The duplication occurs specifically during hydration, not during server-side rendering
• Other pages (home, category, collection, blog) work correctly with their respective metadata generators

Possible Causes

1. Something specific about the product page route structure
2. Next.js 15 hydration bug with certain metadata configurations
3. Client-side component interference (though no client components manipulate metadata)
4. Route-specific metadata handling issue in Next.js 15

This appears to be a Next.js 15 specific issue with metadata handling during hydration on product pages.

Additional information

No response

Example

No response

[Bigpapabiggie69]

i am also using the medusa js v2 next js 15 starter storefront

[icyJoseph]

Could I see some screenshots of the duplication? Assuming it is ok to share. If not, then it is ok.

I want to figure out what are the changes needed to trigger this issue. A page with [slug] or something like that, and then navigating between slugs?

[icyJoseph]

Any other details about what the Product Detail Page does? Is it fully on demand? or pre-rendered?

[Bigpapabiggie69]

Page Structure

• Route: src/app/(main)/products/[handle]/page.tsx
• Template: src/modules/products/templates/index.tsx
• Metadata Generator: src/lib/util/metadata-generator.ts

Metadata Generation

export async function generateMetadata({ params }: Props): Promise<Metadata> {
  const { countryCode, handle } = await params
  
  const result = await getProduct(countryCode, handle)
  const { product } = result
  
  return generateProductMetadata({
    title: product.title,
    description: product.description || `Shop ${product.title} at Company Name.`,
    keywords: product.tags?.map(tag => tag.value) || [],
    canonical: `/products/${product.handle}`,
    ogImage: product.images?.[0]?.url,
    images: product.images?.map(img => img.url) || [],
    price: product.variants?.[0]?.calculated_price?.calculated_amount?.toString(),
    availability: product.variants?.[0]?.inventory_quantity > 0 ? "in stock" : "out of stock",
    brand: product.metadata?.brand || "Company Name",
    category: product.categories?.[0]?.name || "Products",
  })
}

Data Fetching with Caching

const getProduct = cache(async (countryCode: string, handle: string) => {
  const region = await getRegion("gb")
  const pricedProduct = await listProducts({
    countryCode: "gb",
    queryParams: { 
      handle,
      fields: "*variants.calculated_price,+variants.inventory_quantity,+metadata,+tags,+categories.id,+categories.name,+categories.handle,+categories.parent_category,+categories.parent_category.parent_category,+categories.metadata,+categories.parent_category.metadata,+categories.parent_category.id"
    },
  }).then(({ response }) => response.products[0])

  const shippingOptions = await getRegionShippingOptions(region.id)
  return { product: pricedProduct, region, shippingOptions }
})

Metadata Fields Generated

• title - Product title
• description - Product description
• keywords - Product tags
• canonical - Product URL
• ogImage - First product image
• images - All product images array
• price - Product price
• availability - Stock status
• brand - Product brand
• category - Product category
• alternates.canonical - Canonical URL
• openGraph - Full OpenGraph object
• twitter - Twitter card data
• other - Custom metadata fields
• robots - SEO directives

Root Layout Metadata

// src/app/layout.tsx
export const metadata: Metadata = {
  title: {
    template: "%s | Company Name",
    default: "Company Name | Premium Products",
  },
}

export default function RootLayout(props: { children: React.ReactNode }) {
  return (
    <html lang="en" data-mode="light">
      <head>
        {/* Global Organization Schema */}
        <script type="application/ld+json" dangerouslySetInnerHTML={{
          __html: JSON.stringify({
            "@context": "https://schema.org",
            "@type": "Organization",
            name: "Company Name",
            url: "https://company.com",
            logo: "https://company.com/logo.svg",
          }),
        }} />
        {/* Global Website Schema */}
        <script type="application/ld+json" dangerouslySetInnerHTML={{
          __html: JSON.stringify({
            "@context": "https://schema.org",
            "@type": "WebSite",
            name: "Company Name",
            url: "https://company.com",
          }),
        }} />
      </head>
      <body>
        <main>{props.children}</main>
      </body>
    </html>
  )
}

Template Structured Data

// src/modules/products/templates/index.tsx
return (
  <>
    {/* Product Schema */}
    <StructuredData type="product" data={{ product, region, shippingOptions }} />
    
    {/* Breadcrumb Schema */}
    <StructuredData 
      type="breadcrumb" 
      breadcrumbItems={[
        { name: "Home", url: "/" },
        ...breadcrumbChain.map((c: any) => ({
          name: c.name,
          url: `/categories/${c.handle}`
        })),
        { name: product.title, url: `/products/${product.handle}` }
      ]}
    />

    {/* FAQ Schema */}
    <script type="application/ld+json" dangerouslySetInnerHTML={{
      __html: JSON.stringify({
        "@context": "https://schema.org",
        "@type": "FAQPage",
        mainEntity: faqItems.map((f: any) => ({
          "@type": "Question",
          name: String(f.q).trim(),
          acceptedAnswer: { 
            "@type": "Answer", 
            text: stripHtmlForSchema(renderMarkdownToHtml(String(f.a)))
          },
        })),
      }),
    }} />
  </>
)

Metadata Generator

// src/lib/util/metadata-generator.ts
export function generateProductMetadata(config: ProductMetadataConfig): Metadata {
  return {
    title: config.title,
    description: config.description,
    keywords: config.keywords.join(", "),
    alternates: canonicalUrl ? { canonical: canonicalUrl } : undefined,
    robots: {
      index: !config.noIndex,
      follow: !config.noIndex,
      googleBot: {
        index: !config.noIndex,
        follow: !config.noIndex,
        "max-video-preview": -1,
        "max-image-preview": "large",
        "max-snippet": -1,
      },
    },
    openGraph: {
      title: config.title,
      description: config.description,
      url: canonicalUrl,
      images: config.images.length > 0 ? [{
        url: config.images[0],
        width: 1200,
        height: 630,
        alt: config.title,
      }] : undefined,
      type: "website",
      siteName: "Company Name",
      locale: "en_GB",
    },
    twitter: {
      card: "summary_large_image",
      title: config.title,
      description: config.description,
      images: config.images.length > 0 ? [config.images[0]] : undefined,
    },
    other: {
      "product:price:amount": config.price || "",
      "product:availability": config.availability || "",
      "product:brand": config.brand || "",
      "product:category": config.category || "",
      "product:price:currency": "GBP",
    },
  }
}

Structured Data Component

// src/components/seo/structured-data.tsx
export function StructuredData({ type, data, breadcrumbItems }: StructuredDataProps) {
  let structuredData: any = {}

  switch (type) {
    case 'product':
      structuredData = generateProductStructuredData(data.product, data.region, data.shippingOptions)
      break
    case 'breadcrumb':
      structuredData = {
        "@context": "https://schema.org",
        "@type": "BreadcrumbList",
        itemListElement: breadcrumbItems?.map((item, index) => ({
          "@type": "ListItem",
          position: index + 1,
          name: item.name,
          item: item.url,
        }))
      }
      break
  }

  return (
    <Script
      id={`structured-data-${type}`}
      type="application/ld+json"
      dangerouslySetInnerHTML={{ __html: JSON.stringify(structuredData) }}
    />
  )
}

Key Observations

Hydration Behavior

• Server-side: Metadata renders correctly (no duplication)
• Client-side: React hydration duplicates metadata tags
• Timing: Occurs after client load
• Scope: Only affects product pages

[Bigpapabiggie69]

Rendering Strategy

Hybrid Approach: Static Generation + Dynamic Fallback

• Pre-rendered: Known products are built at build time (static)
• On-demand: Unknown/new products render server-side on first request
• Cached: Data fetching prevents duplicate API calls

Page Structure

// src/app/(main)/products/[handle]/page.tsx
import { Metadata } from "next"
import { notFound } from "next/navigation"
import { cache } from "react"
import { listProducts } from "@lib/data/products"
import { getRegion, listRegions, getRegionShippingOptions } from "@lib/data/regions"
import ProductTemplate from "@modules/products/templates"
import { generateProductMetadata } from "@lib/util/metadata-generator"

type Props = {
  params: Promise<{ countryCode: string; handle: string }>
}

// Cached function to fetch product data
const getProduct = cache(async (countryCode: string, handle: string) => {
  const region = await getRegion("gb")
  
  if (!region) {
    return null
  }

  const pricedProduct = await listProducts({
    countryCode: "gb",
    queryParams: { 
      handle,
      fields: "*variants.calculated_price,+variants.inventory_quantity,+metadata,+tags,+categories.id,+categories.name,+categories.handle,+categories.parent_category,+categories.parent_category.parent_category,+categories.metadata,+categories.parent_category.metadata,+categories.parent_category.id"
    },
  }).then(({ response }) => response.products[0])

  const shippingOptions = await getRegionShippingOptions(region.id)
  return { product: pricedProduct, region, shippingOptions }
})

// Generate metadata for product pages
export async function generateMetadata({ params }: Props): Promise<Metadata> {
  const { countryCode, handle } = await params
  
  try {
    const result = await getProduct(countryCode, handle)
    
    if (!result?.product) {
      return {
        title: "Product Not Found",
        description: "The requested product could not be found.",
      }
    }

    const { product } = result
    
    return generateProductMetadata({
      title: product.title,
      description: product.description || `Shop ${product.title} at Company Name.`,
      keywords: product.tags?.map(tag => tag.value) || [],
      canonical: `/products/${product.handle}`,
      ogImage: product.images?.[0]?.url,
      images: product.images?.map(img => img.url) || [],
      price: product.variants?.[0]?.calculated_price?.calculated_amount?.toString(),
      availability: product.variants?.[0]?.inventory_quantity && product.variants[0].inventory_quantity > 0 ? "in stock" : "out of stock",
      brand: (typeof product.metadata?.brand === 'string' ? product.metadata.brand : "Company Name"),
      category: product.categories?.[0]?.name || (typeof product.metadata?.category === 'string' ? product.metadata.category : "Products"),
    })
  } catch (error) {
    console.error("Error generating product metadata:", error)
    return {
      title: "Product",
      description: "Premium products at Company Name.",
    }
  }
}

// Static generation for known products
export async function generateStaticParams() {
  try {
    const countryCodes = await listRegions().then((regions) =>
      regions?.map((r) => r.countries?.map((c) => c.iso_2)).flat()
    )

    if (!countryCodes) {
      return []
    }

    const promises = countryCodes.map(async (country) => {
      const { response } = await listProducts({
        countryCode: country,
        queryParams: { limit: 100, fields: "handle" },
      })

      return {
        country,
        products: response.products,
      }
    })

    const countryProducts = await Promise.all(promises)

    return countryProducts
      .flatMap((countryData) =>
        countryData.products.map((product) => ({
          countryCode: countryData.country,
          handle: product.handle,
        }))
      )
      .filter((param) => param.handle)
  } catch (error) {
    console.error(`Failed to generate static paths for product pages: ${error instanceof Error ? error.message : "Unknown error"}.`)
    return []
  }
}

export default async function ProductPage(props: Props) {
  const params = await props.params
  const result = await getProduct(params.countryCode, params.handle)

  if (!result?.product || !result?.region) {
    notFound()
  }

  return (
    <ProductTemplate
      product={result.product}
      region={result.region}
      shippingOptions={result.shippingOptions}
      countryCode="gb"
    />
  )
}

Template Component

// src/modules/products/templates/index.tsx
import { StructuredData } from "@components/seo/structured-data"

const ProductTemplate: React.FC<ProductTemplateProps> = async ({
  product,
  region,
  shippingOptions,
  countryCode,
}) => {
  // Build breadcrumb category chain
  let breadcrumbChain: any[] = []
  const cats = await listCategories({ limit: 200 })
  const allCats = cats || []
  const productCategories = allCats.filter((c: any) =>
    (c.products || []).some((p: any) => p.id === product.id)
  )

  if (productCategories.length > 0) {
    let leafCategory = null
    for (const cat of productCategories) {
      const hasChildWithProduct = productCategories.some(
        (otherCat: any) => otherCat.parent_category?.id === cat.id
      )
      if (!hasChildWithProduct) {
        leafCategory = cat
        break
      }
    }

    if (leafCategory) {
      const chain: any[] = [leafCategory]
      let cursor: any = leafCategory
      while (cursor?.parent_category) {
        chain.push(cursor.parent_category)
        cursor = cursor.parent_category
      }
      breadcrumbChain = chain.reverse()
    }
  }

  return (
    <>
      {/* Product Schema - Rich snippets for Google */}
      <StructuredData type="product" data={{ product, region, shippingOptions }} />
      
      {/* Breadcrumb Schema - Navigation structure */}
      <StructuredData 
        type="breadcrumb" 
        breadcrumbItems={[
          { name: "Home", url: "/" },
          ...breadcrumbChain.map((c: any) => ({
            name: c.name,
            url: `/categories/${c.handle}`
          })),
          { name: product.title, url: `/products/${product.handle}` }
        ]}
      />

      <div className="bg-[#f7f5f2]">
        <div className="content-container grid grid-cols-1 small:grid-cols-3 gap-6 small:gap-10 py-4">
          {/* Image Gallery */}
          <div className="block w-full relative small:col-span-2">
            <ImageGallery images={product?.images || []} />
          </div>

          {/* Product Info */}
          <div className="small:col-span-1">
            <div className="small:sticky small:top-32">
              <h1 className="font-crimson text-2xl md:text-3xl">
                {product.title}
              </h1>
              <LivePrice product={product} />
              <ProductColors product={product} />
              <ProductHeight product={product} />
              <ProductConfigurator product={product} countryCode={countryCode} />
              <ProductActionsWrapper id={product.id} region={region} />
            </div>
          </div>
        </div>

        {/* Product Info Section */}
        <ProductInfoSection product={product} />

        {/* FAQ Section */}
        {Array.isArray(faqItems) && faqItems.length > 0 && (
          <section className="content-container my-12">
            <h2 className="font-crimson text-2xl md:text-3xl mb-6">
              Frequently asked questions
            </h2>
            <Accordion type="single" collapsible>
              {faqItems.map((f: any, idx: number) => (
                <AccordionItem key={idx} value={`faq-${idx}`}>
                  <AccordionTrigger>
                    <span className="text-lg font-medium">{String(f.q)}</span>
                  </AccordionTrigger>
                  <AccordionContent>
                    <div dangerouslySetInnerHTML={{
                      __html: renderMarkdownToHtml(String(f.a)),
                    }} />
                  </AccordionContent>
                </AccordionItem>
              ))}
            </Accordion>
          </section>
        )}

        {/* Related Products */}
        <div className="content-container my-16">
          <CrossCategoryRecommendations product={product} countryCode={countryCode} />
        </div>
      </div>
    </>
  )
}

Metadata Generator

// src/lib/util/metadata-generator.ts
export function generateProductMetadata(config: ProductMetadataConfig): Metadata {
  const baseUrl = process.env.NEXT_PUBLIC_BASE_URL || "http://localhost:3000"
  const canonicalUrl = config.canonical ? `${baseUrl}${config.canonical}` : undefined

  const otherMetadata: Record<string, string> = {}
  if (config.price) otherMetadata["product:price:amount"] = config.price
  if (config.availability) otherMetadata["product:availability"] = config.availability
  if (config.brand) otherMetadata["product:brand"] = config.brand
  if (config.category) otherMetadata["product:category"] = config.category
  otherMetadata["product:price:currency"] = "GBP"

  return {
    title: config.title,
    description: config.description,
    keywords: config.keywords.join(", "),
    alternates: canonicalUrl ? { canonical: canonicalUrl } : undefined,
    robots: {
      index: !config.noIndex,
      follow: !config.noIndex,
      googleBot: {
        index: !config.noIndex,
        follow: !config.noIndex,
        "max-video-preview": -1,
        "max-image-preview": "large",
        "max-snippet": -1,
      },
    },
    openGraph: {
      title: config.title,
      description: config.description,
      url: canonicalUrl,
      images: config.images.length > 0 ? [{
        url: config.images[0],
        width: 1200,
        height: 630,
        alt: config.title,
      }] : undefined,
      type: "website",
      siteName: "Company Name",
      locale: "en_GB",
    },
    twitter: {
      card: "summary_large_image",
      title: config.title,
      description: config.description,
      images: config.images.length > 0 ? [config.images[0]] : undefined,
    },
    ...(Object.keys(otherMetadata).length > 0 && { other: otherMetadata }),
  }
}

[Bigpapabiggie69]

SOLVED component was calling a server action (trackRecentlyViewed) from a client component during React hydration, which caused Next.js 15 to re-execute the generateMetadata function, leading to metadata duplication.