RFC Search Engine Optimization Meta

[blittle]

Hydrogen provides the getSeoMeta helper function to help developers generate the meta in Remix. This utility is low-level and doesn’t help the developer know what metadata is necessary or best practice for specific types of pages. For example, what metadata is best practice for a product detail page, or a listing page?

We propose adding new helper functions for enumerated page types. These functions will have TypeScript types and runtime checks and produce default metadata for each page type. The resulting metadata can be overridden if the developer wants to change it.

API Signature

We either create new helper function exports, or group them all on the existing export:

getSeoMetaProduct(productData, ...override: SeoConfig[]);

// vs

getSeoMeta.product(productData, ...override: SeoConfig[]);

Page types and default metadata

These are what we propose is “best practice” for each page type:

Root

Used within the root route and common for the whole site, unless overridden by a child route:

  {
    title: string,
    titleTemplate: '%s',
    description: string,
    handle: string,
    url: string,
    robots: {
      noIndex: false,
      noFollow: false,
    },
    jsonLd: {
      '@context': 'https://schema.org',
      '@type': 'Organization',
      name: string,
      logo: string,
      sameAs: [
        'https://twitter.com/shopify',
        'https://facebook.com/shopify',
        'https://instagram.com/shopify',
        'https://youtube.com/shopify',
        'https://tiktok.com/@shopify',
      ],
      url,
      potentialAction: {
        '@type': 'SearchAction',
        target: `${url}search?q={search_term}`,
        query: "required name='search_term'",
      },
    },
  };

Available params:

• Title, description, handle, url, logo, social media links

Questions

• Which available params should be required?
• Should we include SearchAction? It seems if we do, and the developer has different pragma in their search, it would be easy to get bad metadata.

Home page

  {
    title: 'Home',
    description: string,
  };

Available params:

• Title, description

Questions

• These are likely the same as root, so possibly optional params?

Product Detail Page

{
  title: 'string',
  description: 'string',
  media: {
    type: 'image',
    url: string,
    height: number,
    width: number,
    altText: string,
  },
  jsonLd: [
    {
      '@context': 'https://schema.org',
      '@type': 'BreadcrumbList',
      itemListElement: [
        {
          '@type': 'ListItem',
          position: 1,
          name: 'Products',
          item: 'https://hydrogen.shop/products',
        },
        {'@type': 'ListItem', position: 2, name: 'The Hydrogen Snowboard'},
      ],
    },
    {
      '@context': 'https://schema.org',
      '@type': 'Product',
      brand: {'@type': 'Brand', name: 'Snowdevil'},
      description: string,
      image: [
        string,
      ],
      name: 'The Hydrogen Snowboard',
      offers: [
        {
          '@type': 'Offer',
          availability: 'https://schema.org/InStock',
          price: 600,
          priceCurrency: 'USD',
          sku: '',
          url: 'https://hydrogen.shop/products/snowboard?Size=154cm&Binding+mount=Nested&Material=Carbon-fiber',
        },
      ],
      sku: '',
      url: 'https://hydrogen.shop/products/snowboard?Size=154cm&Binding+mount=Nested&Material=Carbon-fiber',
    },
  ],
}

Available params:

• Title, description, media (url, height, width, alt), parentPageUrl (breadcrumb), parentPageName (breadcrumb), brand, availableForSale, price, currency, sku, url

Questions

• Are there other json/ld or other fields “best practice”?

Collection Page

{
  title: string,
  description: string,
  media: {
    type: 'image',
    url: string,
    height: number,
    width: number,
    altText: string,
  },
  jsonLd: [
    {
      '@context': 'https://schema.org',
      '@type': 'BreadcrumbList',
      itemListElement: [
        {
          '@type': 'ListItem',
          position: 1,
          name: 'Collections',
          item: 'hydrogen.shop/collections',
        },
        {'@type': 'ListItem', position: 2, name: 'Freestyle Collection'},
      ],
    },
    {
      '@context': 'https://schema.org',
      '@type': 'CollectionPage',
      name: 'Freestyle snowboards',
      description: string,
      image: string,
      url: '/collections/freestyle',
      mainEntity: {
        '@type': 'ItemList',
        itemListElement: [
          {'@type': 'ListItem', position: 1, url: '/products/snowboard'},
          {'@type': 'ListItem', position: 2, url: '/products/the-full-stack'},
          {'@type': 'ListItem', position: 3, url: '/products/the-h2-snowboard'},
          {
            '@type': 'ListItem',
            position: 4,
            url: '/products/the-hero-snowboard',
          },
          {
            '@type': 'ListItem',
            position: 5,
            url: '/products/the-huebert-snowboard',
          },
          {'@type': 'ListItem', position: 6, url: '/products/the-liquid'},
          {'@type': 'ListItem', position: 7, url: '/products/the-oxygen'},
          {'@type': 'ListItem', position: 8, url: '/products/shopify-aurora'},
        ],
      },
    },
  ],
}

Available params:

• Title, description, media (url, height, width, alt), parentPageUrl (breadcrumb), parentPageName (breadcrumb), products (url, urlPattern), url

Questions

• Are there other json/ld or other fields “best practice”?

Collection Listing Page

{
  title: string,
  description: string,
  media: {
    type: 'image',
    url: string,
    height: number,
    width: number,
    altText: string,
  },
  jsonLd: {
    '@context': 'https://schema.org',
    '@type': 'CollectionPage',
    name: 'Collections',
    description: 'All collections',
    url: 'https://hydrogen.shop/collections',
    mainEntity: {
      '@type': 'ItemList',
      itemListElement: [
        {'@type': 'ListItem', position: 1, url: '/collections/freestyle'},
        {'@type': 'ListItem', position: 2, url: '/collections/backcountry'},
        {
          '@type': 'ListItem',
          position: 3,
          url: '/collections/thermals-and-layers',
        },
        {
          '@type': 'ListItem',
          position: 4,
          url: '/collections/insulated-and-puffy-jackets',
        },
      ],
    },
  },
}

Available params:

• Title, description, media (url, height, width, alt), collections (url, urlPattern), url

Questions

• Are there other json/ld or other fields “best practice”?

Blog

{
  title: string,
  description: string,
  url,
  jsonLd: {
    '@context': 'https://schema.org',
    '@type': 'Blog',
    name: string,
    description: string',
    url,
  },
}

Available params:

• Title, description, url

Questions

• Are there other json/ld or other fields “best practice”?

Article

  {
    title: string,
    description: string,
    titleTemplate: string,
    url,
    media: {
      type: 'image',
      url: string,
      height: number,
      width: number,
      altText: string,
    },
    jsonLd: {
      '@context': 'https://schema.org',
      '@type': 'Article',
      alternativeHeadline: string,
      articleBody: string,
      datePublished: Date,
      description: string,
      headline: string,
      image: string,
      url,
    },
  }

Available params:

• Title, description, url, media (url, height, width, alt), alternativeTitle, datePublished, articleBody

Questions

• Are there other json/ld or other fields “best practice”?

[wizardlyhel]

options to add og tags?

[blittle]

Og tags are already added by getSeoMeta, what I'm proposing here is the default data structures that are sent to getSeoMeta.

[kayluhb]

Hello,

It looks like getSeoMeta is still stripping the params of the canonical URL. I thought I saw a ticket requesting and confirming that params would be left in at a future point, but that didn't seem to make it in the last release of this. It would be great if the function didn't remove parameters from URLs or at least offered the ability to configure that. As it stands right now, I can't really use it as is.

Also, the documentation doesn't appear to be correct.

currently it's

export const meta: MetaFunction<typeof loader> = ({data, matches}) => {
  // Pass one or more arguments, preserving properties from parent routes
  return getSeoMeta((matches as any).data.seo, data!.seo);
};

but that doesn't really work since matches is an array (although maybe that's a typo since I just saw the js version is using the first value of matches).

I think it would be nicer if we could just send an array into the getSeoMeta function. and it would be great if it was typed instead of being cast as an any

export const meta: MetaFunction<typeof loader> = ({data, matches}) => getSeoMeta(matches.map(match => match.data.seo));

[dvnrsn]

It is interesting that Hydrogen has an opinion on stripping query params. It seems like more of a convenience but problematic I agree if page is defined by query param.

Submitted a small PR for docs, but it's also interesting that getSeoMeta is also proposed in migration guide like so

export const meta = ({data, matches}) => {
  return getSeoMeta(...matches.map((match) => match.data.seo));
};

I included this style in PR because I think it's better 🤷🏻

[kayluhb]

Did you test this? Surprisingly, I don't believe this will work with the current implementation of getSeoMeta, since there's a spread operator on the args, but I think it's a little more clear given the data in matches if it were to work with that.

Either way, I believe it should not strip the params from the url.

[dvnrsn]

Yeah we use it in prod. I didn't come up with it. It's from the migration guide that I forgot to link

[blittle]

We intentionally strip the query params, because we've found that to be the most common use case. But getSeoMeta() simply produces a meta array, you can easily override the canonical url to include search params:

export const meta = ({data, location}) => {
  return getSeoMeta(data.seo).map((meta) => {
    if (meta.rel === 'canonical') {
      return {
        ...meta,
        href: meta.href + location.search,
      };
    }

    return meta;
  });
};