Solutions for deduplicated SEO tags

[oscartbeaumont]

I am building a site and want to setup proper SEO tags.

Although newer React versions hoists title and meta tags to the head element it doesn't deduplicate them so if I have a title tag on my default layout and then try and override it with a more specific title tag on a specific page I end up with two tags in the head.

For comparision Next.js has a export const metadata which works pretty well.

Do you have an intention of a built-in SEO system or would it be possible to integrate with something like react-helmet?

Really loving working with Waku!

[dai-shi]

Yeah, I was hoping that React would dedup tags.
If it's their intention to not do it, we will follow that.

There's no plan to provide Nextjs-like APIs, but technically we could solve it with Hono middleware or minimal api (not documented). But they are stream based, and not very handy.

It's much easier to solve within React, and I wonder if you could control yourself to avoid duplicated tags. Would you describe your problem at minimum?

[Master-Hash]

I'm using <title> just in pages and not in layout, which can solve this.

[oscartbeaumont]

Yeah, I was hoping that React would dedup tags.
If it's their intention to not do it, we will follow that.

Looking at the "Pitfall" banner on their docs it seems they have no intention of doing it and callout that it can lead to undefined behavior with search engines.

In the React v19 release notes the React team say that you should concider a framework for handling the meta tags:

It's much easier to solve within React, and I wonder if you could control yourself to avoid duplicated tags. Would you describe your problem at minimum?

I think manually avoiding duplicate tags is what i'm going to do for now but it's kinda rough because it means I can't set any defaults in the layout, I have to remember to set them on each and every page, including when I add new ones. Especially with AI tooling and working in a team, weird conventions like needing a <MetaTags /> component on each page don't scale well in my experience.

In general i've found with any stack it's common to have one or two pages with an override and everything else just be the websites default which I think would be nice if they came from a layout so it can't be forgotten on each page.

Another idea

I wonder if a custom waku.server.ts could enable react-helmet support. I think it might be my best bet if Waku isn't going to directly have APIs for deduplicating SEO tags.

Will give this a shot when I have a moment and report back!

Thanks for all your help taking the time to look at these issues!

[dai-shi]

I think it might be my best bet if Waku isn't going to directly have APIs for deduplicating SEO tags.

Yes, Waku whose goal being minimal won't directly solve it. It should be opt-in solutions.

I'm not familiar with react-helmet, but yeah, that kind of metadata libraries would be nice.

---

Although we probably don't take this approach, using waku.server.tsx, we should be able to parse html stream and dedup some html head tags.

// waku.server.tsx
...
export default adapter(dedupTags(fsRouter(...));

[oscartbeaumont]

Looking into it more react-helmet doesn't seem to really be designed around streaming but it seems like a alternative called react-helmet-async was created to fix this shortcoming.

From reading the Streams section in the readme they say that the head must be rendered outside of the React renderToNodeStream call for it to work which i'm not sure is true for Waku?

Although we probably don't take this approach, using waku.server.tsx, we should be able to parse html stream and dedup some html head tags.

That does make sense but I wonder how that will go when React hydrates? or during client SPA navigation? Would React try and replace the head I wonder or would it be fine with it?

[dai-shi]

the head must be rendered outside of the React renderToNodeStream call for it to work which i'm not sure is true for Waku?

It's false.

how that will go when React hydrates?

Ohhh, good point. It may cause hydration error.

---

I may try another idea. If it doesn't work, probably it's worth considering exporting some internal functions for this.

[dai-shi]

I may try another idea.

Here it is:
https://stackblitz.com/edit/github-jou9mv4g?file=src%2Flib%2Fhead.tsx

React.cache doesn't seem to work on stackblitz, so you need to download it and run locally.

[deepso7]

I may try another idea.

Here it is: https://stackblitz.com/edit/github-jou9mv4g?file=src%2Flib%2Fhead.tsx

React.cache doesn't seem to work on stackblitz, so you need to download it and run locally.

this approach doesn't work on static pages, is there something we could do?

For now, I fixed it using page level head tags instead of layout level

[oscartbeaumont]

This does seem like a interesting solution although I worry it seems a little fragile given from my understanding it depends on React's rendering order quite heavily. For example, what if you were to put a component which attempts to set meta within a Suspense boundary that suspenses on some data, I assume it might not work when streaming is enabled as the HeadTitle would potentially render before the child that uses setHeadTitle. I still need to do some tests to confirm this theory though.

Even so if only used at a page-level and all suspending data was broken out carefully it could work pretty well.

[dai-shi]

this approach doesn't work on static pages, is there something we could do?

Yeah, this approach doesn't work for static layout, because if it's static, we only render once. For static sites, the streaming patch seems better. I haven't tried it, but it may not cause hydration errors.

what if you were to put a component which attempts to set meta within a Suspense boundary that suspenses on some data

I think that's technically impossible, because by that time <head> tag is already sent to the browser.

[dai-shi]

the streaming patch seems better. I haven't tried it, but it may not cause hydration errors.

It seems working.

https://stackblitz.com/edit/github-cz1hu1lw?file=src%2Flib%2Fdedup.ts,src%2Fwaku.server.tsx

This is just a proof of concept. It doesn't do stream processing, and it only handles <title>.

[deepso7]

found this, unhead is also working on stream SSR
not sure how to leverage it in waku
https://unhead.unjs.io/docs/react/head/guides/core-concepts/streaming

[dai-shi]

https://unhead.unjs.io/docs/react/head/guides/core-concepts/streaming/

This is about the case after the head is sent. I think it's already done with React.

[jserrao]

Unhead didn't work for me - it needed a hook useHead so the tags don't exist in the static HTML after your build, only after hydration do they appear. So my pages always looked broken.

I made a component that returns actual JSX elements (like <title> and <meta>) that can fit into the React component tree and extract the JSX when you do a static build. The trade-off I've found is that you can't abstract this into your layout file but it does work to abstract at the page level which is an improvement. Maybe @dai-shi you know why the hoisting only seems to go down one level (great little framework btw)?

/**
 * SEO Types
 *
 * TypeScript interfaces for SEO meta tag configuration.
 */

export interface SEOProps {
  title: string;
  description: string;
  canonicalUrl?: string;
  ogImage?: string;
  ogType?: 'website' | 'article';
  noindex?: boolean;
  additionalMeta?: Array<{
    name?: string;
    property?: string;
    content: string;
  }>;
}

/**
 * Default SEO configuration for the site
 */
export const defaultSEO = {
  siteName: 'YourSite',
  baseUrl: 'https://www.your-site.com',
  defaultOgImage: '/images/OG_1200x630px.jpg',
  twitterHandle: '@yoursite',
} as const;

/**
 * SEO component
 */
export function SEO({
  title,
  description,
  canonicalUrl,
  ogImage,
  ogType = 'website',
  noindex = false,
  additionalMeta = [],
}: SEOProps) {
  
  const fullOgImage = ogImage
    ? ogImage.startsWith('http')
      ? ogImage
      : `${defaultSEO.baseUrl}${ogImage}`
    : `${defaultSEO.baseUrl}${defaultSEO.defaultOgImage}`;

  // Build full canonical URL
  const fullCanonicalUrl = canonicalUrl || defaultSEO.baseUrl;

  return (
    <>
      {/* Standard meta tags */}
      <title>{title}</title>
      <meta name="description" content={description} />
      {noindex && <meta name="robots" content="noindex, nofollow" />}

      {/* Open Graph tags */}
      <meta property="og:title" content={title} />
      <meta property="og:description" content={description} />
      <meta property="og:image" content={fullOgImage} />
      <meta property="og:url" content={fullCanonicalUrl} />
      <meta property="og:type" content={ogType} />
      <meta property="og:site_name" content={defaultSEO.siteName} />

      {/* Twitter Card tags */}
      <meta name="twitter:card" content="summary_large_image" />
      <meta name="twitter:title" content={title} />
      <meta name="twitter:description" content={description} />
      <meta name="twitter:image" content={fullOgImage} />

      {/* Canonical link */}
      <link rel="canonical" href={fullCanonicalUrl} />

      {/* Additional custom meta tags */}
      {additionalMeta.map((meta, index) =>
        meta.property ? (
          <meta key={`meta-${index}`} property={meta.property} content={meta.content} />
        ) : (
          <meta key={`meta-${index}`} name={meta.name} content={meta.content} />
        )
      )}
    </>
  );
} 

/**
 * Example Homepage Usage
 */
import { SEO } from '../components/SEO';

export default async function HomePage() {
  return (
    <>
      <SEO
        title="Your Site"
        description="xyz"
        canonicalUrl="https://www.yoursite.com/"
        ogImage="/images/OG_1200x630px.jpg"
      />
      <div>
      </div>
    </>
  );
}

export const getConfig = async () => {
  return {
    render: 'static',
  } as const;
};

[dai-shi]

why the hoisting only seems to go down one level

Not sure if I get the question.

(great little framework btw)

❤️