RFC: <Head> component #28240

mxstbr · 2020-11-23T16:07:04Z

mxstbr
Nov 23, 2020

Start Date: 2020-11-23
RFC PR: (leave this empty)
Gatsby Issue: (leave this empty)

Summary

Add a <Head> component to Gatsby as the blessed way of adding meta tags to pages.

Basic example

// src/pages/about.js
import React from "react"
import { Head } from "gatsby"

export default (props) => (
  <>
    <Head
      // Basic information handled via props
      title="About Dick's Flower Shop"
      description="Who is Dick and why did he create yet another flower shop"
    >
      {/* Extra meta tags can be added by rendering them as children */}
      <meta name="twitter:site" content="@dicksflowers" />
    </Head>
    <h1>About Us</h1>
  </>
)

Motivation

Gatsby is fantastic for SEO thanks to its outstanding performance. However, we tell users to add page metadata by setting up a non-core plugin (react-helmet) and copy-and-pasting code (!) from our docs.

This is not only confusing and more complex than it needs to be, but also not maintainable. We can never update or improve code users copy-and-paste. We also cannot bake best practices into our SEO setup to make every Gatsby site shine across search and social media by default.

“I spent 3ish hours building a landing page last week and 3ish more hours trying to get a darned open graph image to show up in all the right social media tags. I think something like this would be fantastic.”

– Kyle Gill

Detailed design

In general, this component should work similarly to the <SEO> component from our docs and be based on react-helmet, the standard in the React community.

Compared to normal react-helmet, this <Head> component can leverage the information Gatsby has about a website (specifically, the siteMetadata and current path). On top of that, basic information, such as the page title, is provided via props (instead of manually via meta tags) allowing us to generate a set of "best practice" meta tags that work well across search and social media automatically.

API

Users define the default metadata in the gatsby-config.js via the siteMetadata field:

// gatsby-config.js
module.exports = {
  siteMetadata: {
    title: "Dick's Flower Shop",
    description: "Get a beautiful flower bouquet delivered to your doorstep in less than an hour!",
    baseUrl: "https://dicks.flowers",
    image: "/images/social-media.png",
  }
}

The component is automatically rendered on every page with the default data. That means in the example above, all pages will show "Dick's Flower Shop" as the title.

To override the defaults for a specific page, users import and render the <Head> component on a page and provide different data:

// src/pages/bouquet/{Bouquet.name}.js
import React from "react"
import { Head } from "gatsby"

export default (props) => (
  <>
    <Head
      // Basic information handled via props
      title={props.data.bouquet.name}
      description={`Get ${props.data.bouquet.name} delivered to your doorstep in less than an hour`}
      // Since image="" is not specified it will be set to the default
    >
      {/* Extra meta tags can be added by rendering them as children */}
      <meta name="twitter:site" content="@dicksflowers" />
    </Head>
    <h1>{props.data.bouquet.name}</h1>
  </>
)

export const query = graphql`
  query ($id: String) {
    bouquet(id: { eq: $id }) {
      id
      name
    }
  }
`

To provide a great experience across search and social media, four pieces of information need to be present on every page:

Title (e.g. "Dick's Flower Shop")
Description (e.g. "Get a beautiful flower bouquet delivered to your doorstep in less than an hour!")
Base URL (e.g. "https://dicks.flowers")
Meta Image (e.g. "/images/social-media.png")

With these four basic pieces of information we can create a set of meta tags that work across search and social media:

<title>${title}</title>
<meta name="description" content="${description}" />

<!-- Twitter Card data -->
<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="${image}">

<!-- Open Graph data -->
<meta property="og:title" content="${title}" />
<meta property="og:type" content="website" />
<meta property="og:url" content="${baseUrl}${location.pathname}" />
<meta property="og:image" content="${image}" />
<meta property="og:description" content="${description}" />

To ensure we can always inject these (duplicate) meta tags for the basic information, we let users provide the defaults from siteMetadata (see example above) and users provide the overrides for certain pages via props:

import { Head } from "gatsby"

<Head
  title={props.data.bouquet.name}
  description={`Get ${props.data.bouquet.name} delivered to your doorstep in less than an hour`}
  image={props.data.bouquet.image}
  // We determine and set the URL automatically. It does not need to be provided via props.
>
  {/* Extra meta tags can be added via children */}
  <meta name="twitter:site" content="@dicksflowers" />
</Head>

Drawbacks

This increases our API surface and will need a lot of documentation as well as busywork to update starters and examples
We will own not only react-helmet's API surface area but also issues from our users perspective. If react-helmet has a bug, they'll complain to us.
This will take a while to decide on and implement, distracting us from potentially more important features

Alternatives

Transparent react-helmet wrapper

Rather than owning the entire API surface area (including bugs) of react-helmet I considered "react-helmet built into Gatsby". That could look like this:

import { Helmet } from "gatsby"

<Helmet>
  <meta name="twitter:site" content="@dicksflowers" />
</Helmet>

The upsides of doing this would be that documentation would be much less of a chore (we could point to the react-helmet documentation for advanced use cases) and we wouldn't own react-helmets' bugs (users would know it's a react-helmet bug rather than a Gatsby bug).

However, that could also backfire as it wouldn't be just react-helmet. Instead, it would have to be a wrapper around react-helmet that supports the siteMetadata defaulting and basic information support described above. That means the real API for users would look like this:

import { Helmet } from "gatsby"

// Note how we pass title="" via props rather than rendering <title>
<Helmet title="Dick's Flower Shop">
  <meta name="twitter:site" content="@dicksflowers" />
</Helmet>

That is confusing, as the title prop is not part of the react-helmet API, and neither is the siteMetadata support. So we would have to documentat that yes, this is react-helmet, however it's our special version of it.

That feels like more trouble than it's worth to me. I think the tradeoff of owning that API surface area and the bugs are preferable.

Transparent react-helmet with `Meta` components

To combat the weirdness of wrapping react-helmet, we could also consider introducing special <Meta> (and <MetaTitle>?) components that would be used in place of the standard <meta> elements.

This would allow us to turn <MetaTitle> and other <Meta> components into the recommended set of meta tags automatically. Example usage would look like this:

import { Helmet, Meta, MetaTitle } from "gatsby"

<Helmet>
  <MetaTitle>Title</MetaTitle>
  <Meta name="description" content="Description" />
  <Meta name="twitter:site" content="@username" />
</Helmet>

// ...would turn into...

// General tags
<meta name="twitter:card" content="summary_large_image" />
<meta property="og:type" content="website" />
<meta property="og:url" content="${baseUrl}${location.pathname}" />

// Title
<title>Title</title>
<meta name="twitter:title" content="Title" />
<meta property="og:title" content="Title" />

// Description
<meta name="description" content="Description" />
<meta name="twitter:description" content="Description" />
<meta property="og:description" content="Description" />

// Standard Meta tag
<meta name="twitter:site" content="@username" />

The upside is that this makes the boundary between the (now completely bog standard) react-helmet API and the Gatsby-specific additions very clear. We could again refer straight to the react-helmet documentation.

The downside is that it's more verbose. It could lead to users adding redundant meta tags that we theoretically already add automatically, for example:

<Helmet>
  <MetaTitle>Title</MetaTitle>
  {/* REDUNDANT: <MetaTitle> already does this automatically for them */}
  <Meta property="og:title" content="Title" />
</Helmet>

Adoption strategy

This will work out of the box in all existing Gatsby apps and will be interoperable with the standard <SEO> component highlighted in our docs as it also uses react-helmet.

How we teach this

We must add dedicated documentation for this feature and API surface area, as well as write blog posts on migrating to this new setup.

Unresolved questions

1. How do we let users set default meta tags that should be rendered on every page but not in the `siteMetadata`?

For example, <meta name="twitter:site"> should be set to the site's twitter username on every page (e.g. "@dicksflowers"). Sure, we could add fields for every single potential meta tag (twitterUsername) but that feels unergonomic as there are a lot of meta tags.

Instead, I think we should add a way for users to specify additional "default" meta tags somehow. Maybe we should tell them to render the <Head> component in the gatsby-browser/ssr.js wrapPageElement method like so?

// gatsby-browser.js
exports.wrapPageElement = ({ element, props }) => {
  return (
    <Layout {...props}>
      <Head>
        {/* Default meta tags applied to every page specified here */}
        <meta name="twitter:site" content="@dicksflowers" />
      </Head>
    </Layout>
  )
}

// gatsby-ssr.js
exports.wrapPageElement = require(`./gatsby-browser`).wrapPageElement;

2. Do we enforce that users pass the basic information via props, rather than rendering the meta tags for it?

Even though it would work, we don't want users to render the basic information meta tags themselves as they could forget some parts of the combination:

<Head>
  <title>Dick's Flower Shop</title>
</Head>

Rather, they should pass the basic information via props so it turns into the correct set of meta tags automatically:

<Head title="Dick's Flower Shop" />
<!-- turns into -->
<title>Dick's Flower Shop</title>
<meta name="twitter:title" content="Dick's Flower Shop">
<meta property="og:title" content="Dick's Flower Shop" />

Do we want to enforce that by warning/erroring in the console if they provide meta tags that are also in the basic information?

3. Do we want to fork react-helmet?

We could fork react-helmet to avoid blocking users by upstream bugs we cannot fix. However, we might not be able to benefit from upstream fixes then as our code could diverge from theirs.

4. Do we want to go for the "Transparent react-helmet wrapper with Meta components" API?

See above.

KyleAMathews · 2020-11-23T16:20:39Z

KyleAMathews
Nov 23, 2020

I wonder if there's features/code in React Helmet we could drop by forking. This would make the default Gatsby runtime smaller.

2 replies

sandren Nov 24, 2020

If the aim is to have a simpler API with a smaller impact on bundle size, is there any reason why the new Gatsby <Head /> component can't be a fully custom solution instead of basing it on React Helmet?

mxstbr Nov 24, 2020
Author

react-helmet is battle tested in production across many many React apps. It's highly unlikely that we can build anything better with the same API from scratch, not to mention a pretty big waste of time since it already exists. 😉

We could definitely look into forking it and scrapping some of the features for bundle size wins though!

gillkyle · 2020-11-23T18:28:44Z

gillkyle
Nov 23, 2020

In the "How we teach this" section there might be room for local development-time warnings that could prompt the user to use the API that could make improvements to their SEO like:

warn: identical page title's detected while navigating between pages, consider using 
the <Head> component to add a unique page title and help this page's SEO scores

2 replies

mxstbr Nov 23, 2020
Author

Yes!! We could also warn if the description is longer than the recommended maximum, some parts are missing, the image doesn't match the recommended formats, etc. Lots of ways we could improve the standard experience of "Hope for the best"!

fk Nov 24, 2020
Maintainer

<3 <3 <3

sandren · 2020-11-23T19:10:41Z

sandren
Nov 23, 2020

An official <Head /> component would be a great opportunity to solve an issue many are experiencing with meta tags added by React Helmet being so far down in the <head> that Google doesn't detect the meta description for search engine results pages and Facebook doesn't detect the Open Graph data for social media card images. Therefore it is very important that the content from <Head /> should be added before the inlined critical CSS buries it beyond detection by Google and Facebook.

The issue is described extensively here and here.

0 replies

mfrachet · 2020-11-24T08:21:16Z

mfrachet
Nov 24, 2020

Before jumping on my personal preferences, I would like to thank you so much for this amazing RFC! I love the underlying idea, this is amazing 🚀 🎸

How do we let users set default meta tags that should be rendered on every page but not in the siteMetadata?

This would be okay to me as a person using Gatsby to only rely on the Gatsby Head primitive and build by own <MyAppHeader /> gathering all the mandatory information that could be repeated across pages.

A big advantage would be that it scopes the Head component inside app components and not on gatsby dedicated files/config. It's easier for me to reason about a whole page directly seeing its associated JSX content than jumping between files to understand the inter-dependencies between Gatsby specific files and my application.

That's a very personal opinion I would say, I'm sharing in case other may feel the same 😊

Do we enforce that users pass the basic information via props, rather than rendering the meta tags for it?

If possible, I would warn anytime when people are setting a "raw meta tags" that is already covered by the Gatsby one. This will help people understand the way Gatsby Head is built and drive them in the right direction. That would be very interesting for the DX, I love that idea :D. Also, as mentioned last time, I really like the composition approach using a specific Gatsby Meta component since it doesn't change too much the HTML API but allows for everything mentioned (again, personal preferences I would say)

Do we want to fork react-helmet?

I would say yes from what @KyleAMathews has mentioned, we can get rid off some overhead and rethink the module according to our use cases. More work, but more freedom :).

Do we want to go for the "Transparent react-helmet wrapper with Meta components" API?

I would sign for this one 🗒️ ✍🏻 🚀

0 replies

me4502 · 2020-11-25T04:32:18Z

me4502
Nov 25, 2020

Would this support multiple <Head> components, similar to how React-Helmet supports multiple <Helmet> blocks?

The primary use case for this is being able to ensure that components are responsible for their own Head-data. Eg, a pagination component being responsible for the next/prev page hrefs in the head.

1 reply

mxstbr Nov 25, 2020
Author

Yes!

wardpeet · 2020-11-25T08:15:01Z

wardpeet
Nov 25, 2020

Having a HEAD component in Gatsby adds a lot of benefits. We can capture preload/preconnect headers used deep inside pages and add them as an HTTP header (it would improve gatsby-plugin-image even more).

As mentioned in the RFC, a HEAD component will make it easier for our users to add tags to their websites.

I want to push back on forking/using react-helmet as the base library. React-helmet has served the react helmet well, and the API is 👍. The sad part is that it's not a small library (https://bundlephobia.com/result?p=react-helmet@6.1.0) and not concurrent mode ready. This is not react-helmet's fault as it has to work in every React app. The great thing about Gatsby is that we control the whole lifecycle. We can optimize it for our use case.

I suggest also checking out to draw ideas from:

Questions

What happens when the Head component is not wrapping meta, link, title tags? Do we throw a warning, how will we do that, ...
The head component, by default, takes what's in siteMetadata. Do we want to have the ability to augment the part from GraphQL? Where any cms can extend SiteMetaData.
React is moving to a hooks world. Should we try to make the API more modern and maybe go hooks all the way and drop the components? Or do we think that the components make overriding and nesting easier/more verbose?
Could we move the API to gatsby/head? This might make searching/googling easier for anything related to SEO. cc @hashimwarren

Feature requests

I would highly encourage you to move to create custom components for all supported tags. Why? We can add some built-in optimizations that way.

We can create a script tag that, by default, is set to async. Warn people when using sync tags.
For Link[rel="stylesheet"] we can integrate it in our CSS pipeline. Capture fonts, ...
We can give best practices information for meta tags/SEO like https://web.dev/lighthouse-seo/.
Custom react components give us the benefit of replacing them with AMP variants, ...

0 replies

ehowey · 2020-11-25T14:04:52Z

ehowey
Nov 25, 2020

I like this idea. +1 to Wardpeets comment about being able to pipe in data from GraphQL. I have an SEO component that I pipe data in from SANITY by way of component shadowing a useSiteMetata hook.

So I have a “core” theme with a base SEO component that gets data from Gatsby-config. Then I have a sanity theme which layers on top of the core theme and shadows this SEO component and also shadows my useSitemetadata hook as well to pipe information from SANITY instead of from Gatsby-config.

You can see that here: https://github.com/ehowey/gatsby-theme-catalyst/tree/main/themes/gatsby-theme-catalyst-sanity/src/gatsby-theme-catalyst-core/utils

0 replies

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

RFC: <Head> component #28240

{{title}}

{{editor}}'s edit

{{editor}}'s edit

Replies: 7 comments 5 replies

{{title}}

{{title}}

{{title}}

{{editor}}'s edit

{{editor}}'s edit

{{title}}

{{editor}}'s edit

{{editor}}'s edit

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

{{editor}}'s edit

{{editor}}'s edit

{{title}}

{{editor}}'s edit

{{editor}}'s edit

Select a reply

RFC: <Head> component #28240

Summary

Basic example

Motivation

Detailed design

API

Drawbacks

Alternatives

Transparent react-helmet wrapper

Transparent react-helmet with Meta components

Adoption strategy

How we teach this

Unresolved questions

1. How do we let users set default meta tags that should be rendered on every page but not in the siteMetadata?

2. Do we enforce that users pass the basic information via props, rather than rendering the meta tags for it?

3. Do we want to fork react-helmet?

4. Do we want to go for the "Transparent react-helmet wrapper with Meta components" API?

Replies: 7 comments · 5 replies

mxstbr Nov 24, 2020 Author

mxstbr Nov 23, 2020 Author

fk Nov 24, 2020 Maintainer

mxstbr Nov 25, 2020 Author

Questions

Feature requests

Transparent react-helmet with `Meta` components

1. How do we let users set default meta tags that should be rendered on every page but not in the `siteMetadata`?

Replies: 7 comments 5 replies

mxstbr Nov 24, 2020
Author

mxstbr Nov 23, 2020
Author

fk Nov 24, 2020
Maintainer

mxstbr Nov 25, 2020
Author