RFC: Gatsby Head API

[marvinjude]

Summary

We will be adding a built-in metadata management solution to Gatsby. This will provide an opinionated way to approach metadata in Gatsby sites and provide full compatibility with React 18’s suspense/streaming capabilities.

As of now, users install third-party packages like react-helmet to add metadata to their pages. We intend to make these reliances on third-party packages obsolete and provide a best practice solution directly inside Gatsby.

Basic example

This syntax may change in the future

import React from "react"
import { graphql } from "gatsby";

//Regular page function component
 const MyPageTemplate = ({ pageContext, data, location, path, ...otherProps }) => {
   return (
      <div>
         {/*Use props in template*/}
      </div>
   )
 }
 
//Regular page query
 export const pageQuery = graphql`
  query ContentfulAboutPage($id: String!) {
    contentfulPage(id: { eq: $id }) {
     ...ContentBlocks
     ...SocialMediaImage
     name
     title
     subtitle {
       subtitle
     }
   }
 }`
 
// will receive same props as MyPageTemplate above
 export const Head = ({ pageContext, data, location, path, ...otherProps }) => {
   return (
     <>
       <title>{data.name}</title>
       <meta name="description" content={data.subtitle.subtitle} />
       <link rel="canonical" href="https://www.example.com/about" />
       <link 
         rel="alternate"
         hrefLang="en"
         href="https://www.example.com/about" 
       />
      <link 
        rel="alternate"
        hrefLang="es"
        href="https://www.example.com/es/about"
       />
     </>
   )
 }
 
 export default MyPageTemplate;

Try it out

You can try this feature by installing the latest canary version (experimental, not production-ready) on your site

npm i gatsby@next --save-exact

OR

yarn add --exact gatsby@next

Motivation

Our current recommendation for managing metadata on Gatsby sites, while powerful, is not as simple as it could be. This is not our first attempt at solving this problem, and to quote that original spec:

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.

More recently, customers said this on the topic at GatsbyConf 2022:

It's something I have to do anyway on all sites, so it'd be great if it had the same opinionated 'best-practice' implementation as the rest of Gatsby.

Importing React Helmet can get a bit confusing sometimes. I wish Gatsby had a native API for a page's head component.
We have an opportunity to ease this pain by redefining metadata management "the Gatsby way."
Furthermore, with React 18’s streaming/suspense capabilities the current solutions like react-helmet don’t work correctly anymore and there is a need for a compatible API to define metadata in these environments.

Detailed design

Think of this as a way to add a link, meta, and title tag to a page but outside of the JSX page template itself. We already use this pattern for two existing APIs:

• getServerData for SSR
• config for DSG

We’re introducing a named export function named "Head". This was inspired by Remix

The Head function receives props like data, pageContext and location.pathname. Just like page templates, you need to return valid JSX.

Usage for Globals & Overrides

One common pattern is to have global metadata that you can also override across pages. This is attainable by creating components. that render globals and use them everywhere

//file: src/utils.js
import React from "react";
import { useStaticQuery, graphql } from "gatsby";

export function GlobalHead({ title , children, ...otherProps }){

 const data = useStaticQuery(graphql`
    query HeaderQuery {
      site {
        siteMetadata {
          title
        }
      }
    }
  `);

  return (
     <>
       <title>{title}<title>
       <meta name="GLOBAL" description={data.site.siteMetadata.title} />;
        {/*Some other globals*/}
       { children }
     </>
  )
}

//file: src/pageA.js

import { GlobalHead } from "./utils"

function PageA(){
   return(
     <div>
       Page A content
     </div>
  )
}

export function head(){
  return (
     <GlobalHead title="Page A">
        {/*page specific head additions*/}
     <GlobalHead>
  )
}

export default PageA;

//file: src/pageB.js

import { GlobalHead } from "./utils"

function PageB(){
   return(
     <div>
          Page A content
     </div>
  )
}

export function head(){
  return (
     <GlobalHead title="Page A">
        {/*page specific head additions*/}
     <GlobalHead>
  )
}

export default PageB;

Drawbacks

• Requires more migration effort for users
• We're responsible for handling the half dozen syntaxes that users can use to export named functions (we do this already in our Babel transforms but it's proven tricky)
• Allowing JSX also means allowing any arbitrary component which means we new do extra validation
• We lose most of the composition you’ll normally get with the component approach

Alternatives

A prevalent alternative is the component approach which can be implemented in the following ways

• Building a component from scratch as seen in next/head
• Building a wrapper around common solutions like react-helmet or react-helmet-async

Generally, the approach has some drawbacks that are closely tied to React 18 streaming/suspense. Non-deterministic loading order for resources, delayed discovery of resources and non-deterministic conflict resolution are issues users could run into with React as of today.

Adoption strategy

We intend to make this the default solution for adding metadata to your Gatsby pages. For now, this is especially interesting for those experiencing suspense/streaming-related issues. There is no immediate need to migrate if you don’t run into such problems; however at a later stage, we recommend migrating once the composition drawback is resolved.

How we teach this

We’d need to make it clear to users that we now have a built-in solution for managing page metadata in Gatsby sites.

Existing documentation like https://www.gatsbyjs.com/docs/add-seo-component/ and https://www.gatsbyjs.com/docs/how-to/adding-common-features/seo/#page-metadata
amongst others will have to indicate that Gatsby now provides a solution out of the box and recommend it.

Questions for You

We’d love your feedback on the following :

• Whether you have a better naming suggestion(s) for "head"
• Does this API limit you in what you’re trying to do SEO-wise with Gatsby?
• Do you work around limitations in the currently recommended approaches for managing metadata in Gatsby? If so, please share what you’re doing today, and let us know what you like about those workarounds.

RFC Changelog

• [June 21, 2022] - Initially, we started out with two exports, meta and link allowing you to define links, meta + title in different exports but we soon discovered that the approach wouldn't really lead to a better developer experience and there was no strong technical reason to do that. Now, we use a single export named "head" to define all that needs to go into head
• [July 12, 2022] - (head -> Head): We changed head to Head primarily because we wanted to get React Hot Reloading to work for head exports as this is a requirement for react-refresh-plugin to work properly.

[njbmartin]

One thing not mentioned here is the concept of meta overrides and templates which both react-helmet and next/head handle. My concern with the named export functions approach in its current form is that you end up with a lot of repetitive code throughout when really you just need a generic template and override some values.

In our case, we have an SEO component, which is a wrapper around react-helmet. We have defaults for things like title, description, og:image which is set within our layout, then page / template level we can override it. This approach is of course somewhat opinionated.

// SEO.tsx
import React, { FC } from 'react'
import { graphql, useStaticQuery } from 'gatsby'
import { Helmet } from 'react-helmet'

type SEOProps = {
  description?: string
  title?: string
  metaImage?: string
  keywords?: string[]
}

type Query = {
  site: {
    siteMetadata: {
      title: string
      defaultTitle: string
      description: string
      language: string
      keywords: string[]
      siteUrl: string
    }
  }
  mainImage: { publicUrl: string }
}

export const SEO: FC<SEOProps> = ({
  description,
  keywords,
  title: pageTitle,
  metaImage: pageImage,
}) => {
  const {
    site: {
      siteMetadata: {
        title,
        defaultTitle,
        description: defaultDescription,
        language: lang,
        keywords: defaultKeywords,
        siteUrl,
      },
    },
    mainImage: { publicUrl: metaImageUrl },
  } = useStaticQuery<Query>(graphql`
    query {
      site {
        siteMetadata {
          url
          siteUrl
          title
          defaultTitle
          description
          language
          keywords
        }
      }
      mainImage: contentfulAsset(
        contentful_id: { eq: "3zQPwOSOZIDpJGzLt2HjX9" }
      ) {
        publicUrl
      }
    }
  `)

  const metaTitle = pageTitle || defaultTitle
  const metaDescription = description || defaultDescription
  const seoKeywords = { ...keywords, ...defaultKeywords }
  const metaImage = pageImage || `${siteUrl}${metaImageUrl}`

  return (
    <Helmet
      htmlAttributes={{
        lang,
      }}
      title={metaTitle}
      titleTemplate={`%s | ${title}`}
      meta={[
        {
          name: `description`,
          content: metaDescription,
        },
        {
          property: `og:title`,
          content: title,
        },
        {
          property: `og:description`,
          content: metaDescription,
        },
        {
          property: `og:image`,
          content: metaImage,
        },
        {
          property: `og:type`,
          content: `website`,
        },
        {
          name: `twitter:card`,
          content: `summary_large_image`,
        },
        {
          name: `twitter:title`,
          content: title,
        },
        {
          name: `twitter:description`,
          content: metaDescription,
        },
        {
          name: `twitter:image`,
          content: metaImage,
        },
      ].concat(
        seoKeywords.length > 0
          ? {
              name: `keywords`,
              content: seoKeywords.join(`, `),
            }
          : []
      )}
    />
  )
}

// Layout.tsx

export const Layout: FC<Props> = ({ children }) => {
  return (
    <>
      <SEO />
      ...
    </>
  )
}

// templates/team.tsx
const TeamPage: FC<PageProps<TeamPageProps>> = ({ data }) => {
  const { contentfulTeam } = data

  return (
    <Layout>
      <SEO title={contentfulTeam.teamName} />
      ...
    </Layout>
  )
}

One benefit that Gatsby could introduce as part of this, is a standardised way of creating meta images.

So you could query gatsbyMetaImage instead of gatsbyImage which would automatically transform the image into the correct dimensions.

contentfulAsset(contentful_id: { eq: "3zQPwOSOZIDpJGzLt2HjX9" }) {
  gatsbyMetaImage
}

[KyleAMathews]

Thanks for your comments! Defaults & overrides are a powerful part of react-helmet for sure. Direct support for querying meta images is a very cool idea as well as there's a lot of fiddly details there for sure around what different consumers want and how they're displayed.

[wardpeet]

One thing not mentioned here is the concept of meta overrides and templates which both react-helmet and next/head handle. My concern with the named export functions approach in its current form is that you end up with a lot of repetitive code throughout when really you just need a generic template and override some values.

Perhaps we should add a defaultMeta, defaultLink exports to gatsby-ssr to allow you to define the basics.

[njbmartin]

That could work!

[tujoworker]

First – thank you for making this a part of the framework ✨🙏

I have some questions and thoughts.

Is there a good reason why separate links and meta? Like when it comes to "streaming" maybe? I guess Remix could have some reasons there. But hey also, they do not use JSX, but plain JavaScript objects. I think the JSX approach is 100% much nicer 🔥💯 and we can always extract things out form JSX, even its not directly used as so.

If there are no good "technical" reasons – why separate them – I would love to get it simpler with something like this:

• export default 👉 for the HTML body (as of today)
• export { head } 👉 for the HTML head

With that we:

• make it more logical to include <title> as part of head, and not meta.
• do not need to explain the differences when to use what. Its up to the HTML spec/docs.
• easier to read and understand – when not read the Gatsby docs first.

And I still think, having the option to use something like this import { Head } from 'gatsby' would be a nice addition:

// src/components/SEO.tsx
import { Head } from 'gatsby'
export default function(){
  return <Head> Your head additions </Head>
}

But maybe we should rethink the approach, and rather have to use something like this:

// src/components/SEO.tsx
export function head(){
  return <> Your head additions </>
}

// src/pages/random-page.tsx
import { head } from '../components/SEO.tsx'

export { head }

export default function(){
  return <Head> Your </Head>
}

Surely, a layout.tsx component to wrap a certain set of pages would be a nice addition as well.

// src/pages/layout.tsx

export function head(){
  return <> Your head additions </>
}

// optional default export

[wardpeet]

Thank you but adding it inside the React components as you did with the page component is exactly what we try to avoid. Suspense will add many race conditions which we try to avoid.

[marvinjude]

In addition,

Thoughts on single or multiple named export function has definitely been on top of our minds. Truly, we can't see the benefits of keeping them separated nor are there technical reasons to do so right now. So we are most likely going to merge them.

We are exploring more ways to let users define defaults and overrides. The only way to do this right now is to define a function and use that across exports.

e.g. Let's imagine we have a single named export "head" — usage will like:

//file: src/utils.js
function pageMetaDataGenerator(){
  return (
     <>
       {/*Some global meta and links*/}
     </>
  )
}

and use it like it like so

//file: src/pages/pageA.js
function pageA(){
  return (
     <>
       {/*Page A*/}
     </>
  )
}

export function head(){
   return(
      <pageMetaDataGenerator>
      {/*page specific meta & links */}
   )
}

export default pageA

Thanks again for your thoughts.

[tujoworker]

That would be nice!

My main point was to use only “head” instead of link and meta 👍

[me4502]

One concern I have with this approach, is that any "post processing" that needs to be done on the query results etc to render the page & meta tags now needs to be done twice. While for many cases this would be a non-issue, for more complex pages it could nearly double hydration times.

Might make sense as a separate RFC / project, but would a getStaticData akin to getServerData that takes in the page context & query results, and returns extra data that is passed to both the page render method as well as the head method be possible? This would allow any of this processing to happen only once, and would also potentially allow the data to be stored in page-data.json for each page, dropping the need to run it when the page re-renders in the browser.

An alternate to this would be creating a resolver at the GraphQL layer and querying that, but I feel this is a much simpler and easy to understand solution. Writing customer resolvers in the GraphQL layer feels like a much more advanced feature than is justified for this use case.

[marvinjude]

Hi @me4502,

Thanks for the comment!

Can you provide usage examples with some "post processing" that could double hydration time?

[me4502]

I can't think of a specific example that would actually double it, that was more a potential worst case. A case that I frequently use that can be semi expensive though, is extracting all images from a rich text format in blog posts. Whether it's markdown from remark, images in a Contentful entry, etc. On a few sites I work on we use this for both head element generation (structured data, og:image, etc), as well as the actual body element of the page

[raae]

Could this be solved by adding custom resolvers so its resolved as part of the query and not in the template?

[LekoArts]

Published in Gatsby 4.19: https://www.gatsbyjs.com/docs/reference/release-notes/v4.19/#gatsby-head-api

[mwskwong]

Just noticed right after the release, that Gatsby is converting the " character to &quote;, even when processing structured data. That makes this example https://www.gatsbyjs.com/docs/how-to/adding-common-features/adding-seo-component/#rich-snippets impossible to achieve at the moment.

[moshfeu]

An "ok" solution is to use ” rather than "

[LekoArts]

@mwskwong What makes structured data impossible? Google is happy, e.g. on my personal site where I use Gatsby Head: https://search.google.com/test/rich-results/result/r%2Fbreadcrumbs?id=rGYr6AS0tRo_JqhtMoCkTg

But still, this should probably not be converted this way.

[marvinjude]

We confirmed that this is happening because React does some escaping if children is a string.

The fix here will be to somehow trick React not to do that in cases like this

[mwskwong]

We confirmed that this is happening because React does some escaping if children is a string.

The fix here will be to somehow trick React not to do that in cases like this

I think we can make use of dangerouslySetInnerHTML. Although hacky and "dangerous", I'm not sure whether there is a better way because after all, you are gonna trick React not to encode the " any way.

[marvinjude]

You can follow up on the PR to fix this in #36174

[mwskwong]

You can follow up on the PR to fix this in #36174

I read the PR. Do we really want a "fix" like this? Would it be better to use dangerouslySetInnerHTML directly in the document and explain why this has to be done, instead of using dangerouslySetInnerHTML under the hood?

[LekoArts]

Using it in userland won't suffice, I tried it in LekoArts/portfolio-v2@cfee562 - still had the quotes in it with current version

[dan-mba]

I have a couple of questions.

How does the new Head API merge with onRenderBody function setHeadComponents?
Is setHeadComponents the recommended way for a plugin to add to head for all pages?
I use a plugin which currently uses helmet to set the meta viewport on all pages & want to know the recommended way to migrate.

Does the Head API work alongside helmet?
Can you migrate piecemeal or is it all or nothing?

[marvinjude]

Hi @dan-mba,

How does the new Head API merge with onRenderBody function setHeadComponents?

We use setHeadComponents behind the scenes to add the tags you define in your Head export to static HTML

Is setHeadComponents the recommended way for a plugin to add to head for all pages?

Yes

I use a plugin which currently uses helmet to set the meta viewport on all pages & want to know the recommended way to migrate.

We commend using setHeadComponents in cases like this

Does the Head API work alongside helmet?
Can you migrate piecemeal or is it all or nothing?

It works along side react-helmet and you can definitely migrate piecemeal

[wahidshafique]

Is it possible for me to access redux provider inside this component?

[marvinjude]

Hi @wahidshafique,

As of now, this is not possible. Please see #35841 (reply in thread)

[janaagaard75]

Does this API limit you in what you’re trying to do SEO-wise with Gatsby?

Yes, I think it does. I am currently using react-helmet so set the language of the pages with a lang attribute added to all pages, (e.g. ). Is it correct Gatsby Head does not have something equivalent? Should I be using another API so set this attribute?

[manusa]

Thx @marvinjude the solution worked for me.

It might be worth documenting this too. All of the starters and setHtmlAttributes references in this organization reference just how to add the attributes with static values.

I was only able to find the solution after running this search https://github.com/search?q=org%3Agatsbyjs+setHtmlAttributes and finding this discussion.

The loadPageDataSync is not mentioned either in the gastby-ssr docs

Relates to #29734

[manusa]

I created this #36354 just in case

[sallakos]

As @dandroos mentioned, we need to be able to change the language while navigating through the site. Is the only solution to this to not use Gatsby's Link when navigating to another language?

[jerehut]

@marvinjude that solution errors my SSR, am I doing something wrong? This part of it errors it:

exports.onRenderBody = ({ pathname, setHtmlAttributes, loadPageDataSync }) => {
    const {
        result: { pageContext },
    } = loadPageDataSync(pathname);
}

Error just says:

warn The path "/" errored during SSR.      
Edit its component :2:18 to resolve the error.

@manusa what does your working code look like? Thank you :)

[openscript]

It seems like loadPageDataSync is not implemented in all environments: #36675 (comment)

[kije]

Is there a way to access data from context providers that are used to wrap the pages via the wrapRootElement and/or wrapPageElement APIs?

E.g. when using a i18n library (e.g. gatsby-plugin-react-i18next), one might want to use translated strings in the Head component as well.
As this is something that's very specific to the used plugin, it might be a good idea to have an additional API wrapHeadElement similar to wrapRootElement / wrapPageElement which plugins can use to also wrap providers around the contents of Head if it makes sense for that plugin

[ZeldOcarina]

I think it doesn't make too much sense though.. This way we will still need to use other ways and adoption of this new Head component would be impaired imho..

[ZeldOcarina]

@marvinjude 5 months in, do we have any ETA on this? :)
Let me know if I could help in any way, right now I have found some hacky workaround using gatsby-node as the context I was using was not runtime-determined but I think it would be still a nice feature to have.
Thank you!

[JustFly1984]

I have one project on hold, due to this issue.

[openscript]

@LekoArts I would also be happy to finally move to Gatsby Head API.

[sargsyan]

it's surprising that there is no official recommendation from gatsby for multilanguage websites. Also seems that the gatsby-theme-i18n adds react-helmet components to all pages. So with 118n websites, you can't skip loading react-helmet in your pages even if you use Gatsby Head API.

[fshowalter]

Hey all, apologies if I'm missing something easy, but migrating to the new API from react-helmet, it's not clear how to make it work with Jest tests. Typically, I just want to make sure the title and SEO meta are set correctly for a given page. With react-helmet, I had to mock it to render a simple version that bypassed using a static query, but in my page specs I was able to query the document.title and ensure it's correctness.

With the new head-api, the head tag is always rendered empty by Jest so this approach no longer works. Suggestions?

[fshowalter]

Found a work-around. Since the Head function is exported, import said function into my tests, render it into the document.head, and check the result. Not ideal (depends on the test knowing how Gatsby's head-api works) but it'll do.

[LekoArts]

I personally test it like this: https://www.lekoarts.de/garden/testing-gatsby-s-head-api-with-vitest-and-playwright

[fshowalter]

Yup, found that and it pointed me in the right direction. I've come around to liking this method over the old way, which required using a requestAnimationFrame hack to allow react-helmet to fire its updates before querying in the tests. Just rendering the exported Head component is all you need, though if you're testing an SEO component like above, you'll need to specify the head container.

[openscript]

I'm very happy to see the progress on this topic. I'm developing a little i18n plugin for Gatsby. How would you integrate the new Head API into a plugin?

[openscript]

Sounds great, but I'm not sure if I can use setHeadComponents as I cannot access the page context or other contexts from onRenderBody, right? I need the page context for finding out what translations a page has, so I can set the <link rel="alternate" hrefLang="xy" ... /> tags. I think for the same reason your example of i18n is also still using Helmet: https://github.com/gatsbyjs/themes/tree/master/packages/gatsby-theme-i18n#readme

[marvinjude]

You can actually access the page context this way #35841 (reply in thread)

[openscript]

I've revisited the topic, but I'm still stuck. There are no type definitions for loadPageDataSync. I've created the following PR: #36492

[openscript]

@marvinjude It seems like loadPageDataSync is not implemented for development: #36675 (comment)

[openscript]

@marvinjude any updates on this?

[lezan]

Just wondering if it could be possible that if I define propTypes for Head() function, something like that

export function Head({ data: { infoPage, banner }, location }) {
  const { description } = infoPage.nodes[0];

  return (
    <SEO
      title="About us"
      description={description}
      banner={banner}
      pathname={location?.pathname}
    />
  );
}

Head.propTypes = {
  data: PropTypes.objectOf(Object).isRequired,
  location: PropTypes.objectOf(Object).isRequired,
};

the page does not render with some console error

EnsureResources was not able to find resources for path: "/about"
This typically means that an issue occurred building components for that path.
Run `gatsby clean` to remove any cached elements.

Uncaught ReferenceError: Head is not defined
    <anonymous> index.js:148
    default component---src-pages-about-index-js.js:522
    factory commons.js:3873
    __webpack_require__ commons.js:3220
    fn commons.js:3530
    promise callback*componentSrcPagesAboutIndexJs async-requires.js:4
    loadComponent dev-loader.js:39
    inFlightPromise loader.js:268
    promise callback*loadPage loader.js:247
    loadPage dev-loader.js:75
    <anonymous> app.js:152
    promise callback* app.js:86
    js commons.js:1193
    factory commons.js:3873
    __webpack_require__ commons.js:3220
    __webpack_exports__ commons.js:4587
    O commons.js:3269
    <anonymous> commons.js:4588
    <anonymous> commons.js:4590

The above error occurred in the <EnsureResources> component:

EnsureResources@webpack-internal:///./.cache/ensure-resources.js:23:30
LocationHandler@webpack-internal:///./.cache/root.js:68:29
LocationProvider@webpack-internal:///./node_modules/@gatsbyjs/reach-router/es/index.js:86:20
Location@webpack-internal:///./node_modules/@gatsbyjs/reach-router/es/index.js:66:18
Root
StoreProvider@webpack-internal:///./src/context/StoreProvider.jsx:34:18
PartytownProvider@webpack-internal:///./node_modules/gatsby/dist/internal-plugins/partytown/gatsby-browser.js:16:27
StaticQueryStore@webpack-internal:///./.cache/query-result-store.js:159:32
ErrorBoundary@webpack-internal:///./.cache/fast-refresh-overlay/components/error-boundary.js:25:35
DevOverlay@webpack-internal:///./.cache/fast-refresh-overlay/index.js:126:18
RootWrappedWithOverlayAndProvider
App@webpack-internal:///./.cache/app.js:190:78

If I remove the propTypes definition the page is rendered without errors.

[LekoArts]

Under the hood the Head export is removed from the bundle as React Fast Refresh (https://www.gatsbyjs.com/docs/reference/local-development/fast-refresh/) only allows a single (default) export. So your propTypes can't reference it as it's removed from the bundle.

I'd highly recommend using TypeScript, this way you'll get type safety.

[lezan]

Hello @LekoArts, I really appreciate your answer. Thanks!
I am sorry but what is the second default export? In this situation:

function About({...}) {
  ...
}

About.propTypes = {
  ...
}

export default About;

export function Head({...}) {
  ...
}

Head.propTypes = {
  ...
};

The first one default export is export default About; and the second one?

[LekoArts]

It only allows a single export, that's what I meant. That's why we remove the Head export

[lezan]

Hello @LekoArts, I am sorry to waste your time, but I think I am not figure out what you mean. If I can read something more about this kind of issue, please link it because I am not able to find something useful.

So this one work

function About({...}) {
  ...
}

About.propTypes = {
  ...
}

export default About;

export function Head({...}) {
  ...
}

also this one

function About({...}) {
  ...
}

export default About;

export function Head({...}) {
  ...
}

but there is a double export in both (as also reported here).

Thanks!

[openscript]

How to migrate to Gatsby Head API without having in every page and template a head, even though they are all the same?

I have layout components, which I use in pages and templates. Like a <DefaultLayout />. To the layouts some props get passed like a subtitle, keywords or other meta information. Within the layout components I load another component, which creates the head elements.

My questions are:

1. How can I define a default Head component, without reexporting it from every template? If I have to to this, the code would be less DRY.
2. How can a page or template pass props to the Head components?

[marvinjude]

Hi @openscript,

After removing the other component that takes props passed into <DefaultLayout/>, you'd have to add a Head export to all pages / templates and pass those props directly to the component in your Head export (see https://github.com/gatsbyjs/gatsby-starter-shopify/blob/main/src/pages/cart.jsx#L124)

Just like the page component, Head receives a set of props. You can't pass in new props, the best you can do is to create a new component and render that in your Head export (see https://github.com/gatsbyjs/gatsby-starter-shopify/blob/main/src/pages/products/%7BShopifyProduct.productType%7D/%7BShopifyProduct.handle%7D.jsx#L209-L227)

[basnetsoyuj]

I am currently sharing a theme state between head and body to implement dark mode feature in my website:

const Layout = ({ children }) => {
    const [theme, setTheme] = useState('light')

    const onUpdateTheme = () => {
        const newTheme = theme === 'dark' ? 'light' : 'dark'
        window.localStorage.setItem('theme', newTheme)
        setTheme(newTheme)
    }

    useEffect(() => {
        const savedTheme = window.localStorage.getItem('theme')
        if (savedTheme)
            setTheme(savedTheme)
    }, [])

    return (
        <div>
          <Helmet>
            <link rel="shortcut icon" type="image/png" href={favicon} />
            {theme === 'dark' && (
              <link rel="stylesheet" type="text/css" href="/dark-mode.css" />
            )}
          </Helmet>
    
          <div id="layout" className="layout">
            <Navigation onUpdateTheme={onUpdateTheme} theme={theme} />
            <main>{children}</main>
            <Footer />
          </div>
        </div>
      )
}

But with the implementation of Gatsby Head API, it has to be separated into two different exports.

How do I share this state between the head and the body (using React Context also does not make sense hierarchically.)

[JustFly1984]

Hello @LekoArts I have an issue after implementing new Head API. In my project I'm using react-intl and it has a Provider in wrapRootElement. The issue is that I have translation components in Head component, and it requires an access to provider.
Currently it causes a warning in dev, which could be closed without app crash, but prod build is crashing with:

ERROR #95313 

Building static HTML failed for path "/"

See our docs page for more info on this error: https://gatsby.dev/debug-html


  74 |     if (Err === void 0) { Err = Error; }
  75 |     if (!condition) {
> 76 |         throw new Err(message);
     | ^
  77 |     }
  78 | }
  79 |


  WebpackError: [React Intl] Could not find required `intl` object. <IntlProvider> needs to
   exist in the component ancestry.

So I'm stuck. It was working perfectly before migration to new Head API. I did too much changes to roll it back. Please wrap Head in wrapRootElement

[marvinjude]

Hi,

We are sorry you're experiencing this issue. As we mentioned in other comments / discussions like #36551 — What you're experiencing is a current limitation and will be addressed in v5

[JustFly1984]

@marvinjude When should we expect v5? I need to deploy to QA tomorrow, but build is broken with no provided workaround :(

[JustFly1984]

@marvinjude Looking at v5 right now, and an error is the same as in previous versions! wrapRootElement is not implemented!!!

[LekoArts]

Please see #35841 (reply in thread)

[cometkim]

Made this plugin to use with Head API.

https://github.com/cometkim/gatsby-plugin-head-seo

[openscript]

Is it possible to define a default Head component, which applies to all pages, which don't have a Head?

[openscript]

Hi @marvinjude

It would be great to mention all the drawbacks of Gatsby Head API in the docs, so people don't waste time if the migration from Helmet is not worth it.

[openscript]

Approaches like won't work either, because if someone navigates with a link, the head won't be hydrated.

import { RenderBodyArgs } from 'gatsby';

export async function InjectPageMetaData({ loadPageDataSync, pathname, setHeadComponents }: RenderBodyArgs) {
  // loadPageDataSync is not implemented in all run modes like development
  // https://github.com/gatsbyjs/gatsby/issues/36675
  if (!loadPageDataSync) {
    return;
  }

  const {
    result: { pageContext },
  } = loadPageDataSync(pathname) as { result: { pageContext: Queries.SitePageContext } };

  setHeadComponents([
    <title key="pageTitle">{pageContext.metaData?.title}</title>,
    <meta key="pageDescription" name="description" content={pageContext.metaData?.description} />,
  ]);
}

[marvinjude]

Our recommendation to use the loadPageDataSync API was a mistake on our part. As it is a low-level, undocumented API, and does not fully address the problem that users are trying to solve.

For the perceived limitation, We briefly talked about it in our "Introducing the Gatsby Head API" blog post. We would update our documentation to ensure that this is more obvious to users.

[openscript]

@marvinjude Thank you for your reply. Is there another solution to be more DRY on with multiple pages and a default Head?

[marvinjude]

The best you can do right now is to put the tags in a component and export that in each page

[openscript]

How to internationalize Head content like the title or the description meta tag?

export function Head() {
  const intl = useIntl();
  return <Document title={intl.formatMessage('page.home')} />;
}

Something like this doesn't work, as the Head component is not wrapped by any providers.

[cometkim]

It is possible by injecting locale by page context

[openscript]

So I should put all translations (200-300kb) into the page context?

[LekoArts]

We're working on a PR so that context providers in wrapRootElement are wrapping Head, too: #37439

[violy]

I'm trying to migrate a site with Head Api (from react-helmet), but the whole pages uses gatsby-node Api, with createPage().

It's seems that the Head Api is not yet supported with createPage ? I've the following warning :

In page templates only a default export of a valid React component and the named exports of a page query, getServerData or config are allowed.
All other named exports will cause Fast Refresh to not preserve local component state and do a full refresh.
Please move your other named exports to another file. Also make sure that you only export page queries that use the "graphql" tag from "gatsby".

Is this feature on the roadmap ? Or now, should I also migrate my whole code from Node Api to File Api … ?

Thanks.

[marvinjude]

Hi @violy,

Sorry you're running into this. The Head API works fine in page templates and this shouldn't be happening. Please make sure you have v4.19 or greater installed. If this persists, please create an issue with a minimal reproduction

[violy]

You are right ! I have v4.17. Moving on v4.24 works fine. Sorry !

[violy]

I'm migrating a site from react-helmet to Head API, and it's work fine now !

Site pages are in two languages and I want to set HTML attribute lang
The documentation say that I should use gatsy-ssr.js with setHtmlAttributes but it has API no effect on static generation.

but for this site, I only use Gatsby with static generation, not SSR. Is it a workaround !?

[violy]

Thank you for your support and reporting @LekoArts this change is welcome.

[ZeldOcarina]

@LekoArts @marvinjude would this include the ability to use global context in the Head elements too? 🤩

[LekoArts]

@ZeldOcarina what do you mean with "global context"?

[ZeldOcarina]

I mean a Context element that is wrapped on the page element!

[LekoArts]

#35841 (reply in thread)

[albertot]

What about ssr pages ? how do i get the server data within the head function? looks like i can only get: location, params, data, pageContext.

[marvinjude]

Hey @albertot,

As of now, we do not pass in serverData to Head as this was omitted during development. While we focus on Improving the Head API early this quarter please use react-helmet for this case

[LekoArts]

You'll be able to use it with Gatsby 5.5. as #37500 was merged

[witcradg]

some things can be pushed into html.js

…

On Sun, Jan 8, 2023, 11:22 PM Lennart ***@***.***> wrote: Hey! We hear you loud and clear about necessary improvements to the Head API, it's on our radar. It's definitely not about that we *can't* do it, between all the user requests you'd just have to prioritize your time (small team, finite amount of time). And before EOY we spent it on #37069 <#37069> Once we prioritized internally when to tackle this I'll let you know. In the meantime, you can still use react-helmet — Reply to this email directly, view it on GitHub <#35841 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AA4MU33HU256UVCBH547EJTWRO4BRANCNFSM5XZKURMA> . You are receiving this because you commented.Message ID: ***@***.***>

[witcradg]

Thank you.

[1eastar]

HEAD cannot be used in mdx template. Is there any other way other than defining in mdx file directly?

[LekoArts]

That's not correct, it can be used: https://github.com/gatsbyjs/gatsby/blob/master/examples/using-mdx/src/templates/posts.jsx

[1eastar]

Thank you!
I thought I couldn't use HEAD because the template wasn't in the src/page directory.

[LekoArts]

I've updated the first bulletpoint in https://www.gatsbyjs.com/docs/reference/built-in-components/gatsby-head/#usage-notes - hope that makes it clearer?

[1eastar]

That's good enough, but i think it's better to be here too
https://www.gatsbyjs.com/docs/how-to/routing/mdx/#make-a-layout-template-for-your-posts

[marvinjude]

Hey Everyone 👋

We've recently added a new feature that allows setting <html> and <body> attributes in [email protected]. For more information, check out the docs at https://www.gatsbyjs.com/docs/reference/built-in-components/gatsby-head/#editing-html-and-body.

Additionally, we've wrapped Head with wrapRootElement to enable the consumption of React context from Head. This will be available in the next stable release of Gatsby, but you can try it out in gatsby@next

[danilobuerger]

@marvinjude Thanks for the update. If wrapRootElement is soon available for Head, wouldn't it make sense to also consider #33594 (which asks to add pathname to browser as its already supported by ssr). Without the pathname it would be hard for i18n providers detect the language.

[openscript]

What is the suggestion for a plugin, which uses the Gatsby Head API? Currently I'm still relaying on loadPageDataSync which shouldn't be used anymore as far as I understood. How can I export a default head from inside a plugin?

https://github.com/openscript-ch/gatsby-plugin-i18n-l10n/blob/da7446056b8faca21ddaa4d1a16c6115fb8beae9/src/onRenderBody.tsx#L4-L27

[JustFly1984]

I'm currently updating my gatsby project, and trying to fix the Head API. The sad thing that I can't use pageContext in wrapRootElement has no access to pageContext, so I can't use react-intel's IntlProvider.
wrapPageElement is not wrapping Head components, so the only solution which is ugly - I had to wrap Head into IntelProvider in each page template file.

After that I've almost pulled my hair out for another 2 hours, trying to debug something what actually is not broken. Somebody has monkeypatched console.error in head-export-handler-for-browser.js file,

and this just crashes my app in the place where console.error should behave correct, but now it does not! Please forbid monkeypatching!!!

[JustFly1984]

Now I can't debug which console.error actually fails, cos all of them fails in case of try/catch works

[JustFly1984]

Can you please pass the pageContext into wrapRootElement's argument?

[JustFly1984]

The only way to debug an error was to comment out Head API for a specific page which had an error.

[itDw62ST5U]

The Head API uses the ReactContext of the wrapRootElement since version 5.6.0. Typically, the ThemeProviders for styling are also included here. This leads to duplicate <Style> codes in the head and body of the HTML page when generating the code. To avoid this, the ThemeProvider must be included in the wrapPageElement. In the browser, however, the entire theming is now recalculated with every page change, which cannot be intentional. What is the solution for this problem?

export function wrapRootElement({element}) { return ( <ThemeProvider theme={theme}> <CssBaseline/> {element} </ThemeProvider> ) }

vs.

export function wrapPageElement({element, props}) { return ( <ThemeProvider theme={theme}> <CssBaseline/> <Layout {...props}> {element} </Layout> </ThemeProvider> ) }

[sandikodev]

please look and organize them carefully, here is mine....

/** @param {import("gatsby").WrapPageElementBrowserArgs} */
export const wrapPageElement = ({ element, props }) => {
  // props provide same data to Layout as Page element will get
  // including location, data, etc - you don't need to pass it
  return (
    <Layout {...props}>
      {element}
    </Layout>
  )
}

/** @param {import("gatsby").WrapRootElementBrowserArgs} */
export const wrapRootElement= ({ element }) => {
  return <ThemeProvider>{element}</ThemeProvider>;
};

based on my case:

1. wrapRootElement
   a. Here we declare ThemeProvider created by createContext, which inside we just passed down ->
   b. {theme,setTheme} created with useState then ->
   c. onDidMount (with useEffect) dont forget to auto apply wheter if localstorage have theme value set and then they can apply suddenly to the context (by useState)
   d. Why ??: We must get the context lives on apps which mean globaly so we must declare provider most on top of app (root: as the name wrapRootElement)
2. wrapPageElement
   a. Nothing Special here, just declare Layout(Page css Stuff) as you want
   b. you can consume your context using hook or JSX context consumer

   <ThemeContext.Consumer>
      {(value)=>(
         <div its-okay-to-tag={value.theme}> do your some cool stuff here</div>
      )}
    <ThemeContext.Consumer>
   

   c. Why ??: basicaly wrapPageElement just automaticly generate all you need/have same do ${__dirname}/src/pages/**/*.{tsx,jsx}

in nextjs terminology(pages router based): it's same as _document.{jsx,tsx} vs _app.{jsx,tsx}
but now in app router based the _document.tsx and _app.tsx was replaced with layout.tsx because nextjs >13 already(2022) moved as server-first approach

nb: cmiiw

[tony-gutierrez]

Came here to verify Head still cannot be used in a component. It can't replace react-helmet if it requires duping code in every page.

[dannylin108]

Just wondering, why Gatsby Head renders a semi-duplicated tree of all high level components, so all wrapped with wrapRootElement code is fired twice ?

So in this code 'TopLayout re-rendered' would be printed twice if using Gatsby Head on page components and once if not.

export const wrapRootElement: GatsbyBrowser["wrapRootElement"] = ({
    element,
}) => <TopLayout>{element}</TopLayout>;


function TopLayout({children}: TopLayoutProps) {

    console.log('TopLayout re-rendered');
  
    return (
            <ThemeProvider theme={theme}>
                    {children}
            </ThemeProvider>
    );
}

[xray-robot]

As written above, wrapRootElement is run twice if the Head API is used.

Is this a bug or a feature? It should at least be documented.