feat(gatsby): Gatsby Head API

e2e-tests/development-runtime/cypress/integration/head-function-export/all-props.js

@@ -0,0 +1,23 @@
+import { page } from "../../../shared-data/head-function-export.js"
+
+it.only(`head function export should get all page properties`, () => {
+  cy.visit(page.allProps)
+  cy.getTestElement(`location.origin`)
+    .invoke(`attr`, `content`)
+    .should(`equal`, `http://localhost:8000`)
+  cy.getTestElement(`pageContext`)
+    .invoke(`attr`, `content`)
+    .should(`not.be.undefined`)
+  cy.getTestElement(`pageResources.page.componentChunkName`)
+    .invoke(`attr`, `content`)
+    .should(`equal`, `component---src-pages-head-function-export-all-props-js`)
+  cy.getTestElement(`params`)
+    .invoke(`attr`, `content`)
+    .should(`not.be.undefined`)
+  cy.getTestElement(`path`)
+    .invoke(`attr`, `content`)
+    .should(`equal`, `/head-function-export/all-props/`)
+  cy.getTestElement(`uri`)
+    .invoke(`attr`, `content`)
+    .should(`equal`, `/head-function-export/all-props`)
+})

e2e-tests/development-runtime/cypress/integration/head-function-export/html-insertion.js

@@ -0,0 +1,67 @@
+import { page, data } from "../../../shared-data/head-function-export.js"
+
+describe(`head function export html insertion`, () => {
+  it(`should work with static data`, () => {
+    cy.visit(page.basic)
+    cy.getTestElement(`base`)
+      .invoke(`attr`, `href`)
+      .should(`equal`, data.static.base)
+    cy.getTestElement(`title`).should(`have.text`, data.static.title)
+    cy.getTestElement(`meta`)
+      .invoke(`attr`, `content`)
+      .should(`equal`, data.static.meta)
+    cy.getTestElement(`noscript`).should(`have.text`, data.static.noscript)
+    cy.getTestElement(`style`).should(`contain`, data.static.style)
+    cy.getTestElement(`link`)
+      .invoke(`attr`, `href`)
+      .should(`equal`, data.static.link)
+  })
+
+  it(`should work with data from a page query`, () => {
+    cy.visit(page.pageQuery)
+    cy.getTestElement(`base`)
+      .invoke(`attr`, `href`)
+      .should(`equal`, data.queried.base)
+    cy.getTestElement(`title`).should(`have.text`, data.queried.title)
+    cy.getTestElement(`meta`)
+      .invoke(`attr`, `content`)
+      .should(`equal`, data.queried.meta)
+    cy.getTestElement(`noscript`).should(`have.text`, data.queried.noscript)
+    cy.getTestElement(`style`).should(`contain`, data.queried.style)
+    cy.getTestElement(`link`)
+      .invoke(`attr`, `href`)
+      .should(`equal`, data.queried.link)
+  })
+
+  it(`should work when a head function with static data is re-exported from the page`, () => {
+    cy.visit(page.reExport)
+    cy.getTestElement(`base`)
+      .invoke(`attr`, `href`)
+      .should(`equal`, data.static.base)
+    cy.getTestElement(`title`).should(`have.text`, data.static.title)
+    cy.getTestElement(`meta`)
+      .invoke(`attr`, `content`)
+      .should(`equal`, data.static.meta)
+    cy.getTestElement(`noscript`).should(`have.text`, data.static.noscript)
+    cy.getTestElement(`style`).should(`contain`, data.static.style)
+    cy.getTestElement(`link`)
+      .invoke(`attr`, `href`)
+      .should(`equal`, data.static.link)
+  })
+
+  it(`should work when an imported head component with queried data is used`, () => {
+    cy.visit(page.staticQuery)
+    cy.getTestElement(`base`)
+      .invoke(`attr`, `href`)
+      .should(`equal`, data.queried.base)
+    cy.getTestElement(`title`).should(`have.text`, data.queried.title)
+    cy.getTestElement(`meta`)
+      .invoke(`attr`, `content`)
+      .should(`equal`, data.queried.meta)
+    cy.getTestElement(`noscript`).should(`have.text`, data.queried.noscript)
+    cy.getTestElement(`style`).should(`contain`, data.queried.style)
+    cy.getTestElement(`link`)
+      .invoke(`attr`, `href`)
+      .should(`equal`, data.queried.link)
+  })
+})

e2e-tests/development-runtime/cypress/integration/head-function-export/navigation.js

@@ -0,0 +1,56 @@
+import { page, data } from "../../../shared-data/head-function-export.js"
+
+// No need to test SSR navigation (anchor tags) because it's effectively covered in the html insertion tests
+
+it(`head function export behavior during CSR navigation (Gatsby Link)`, () => {
+  // Initial load
+  cy.visit(page.basic)
+
+  // Validate data from initial load
+  cy.getTestElement(`base`)
+    .invoke(`attr`, `href`)
+    .should(`equal`, data.static.base)
+  cy.getTestElement(`title`).should(`have.text`, data.static.title)
+  cy.getTestElement(`meta`)
+    .invoke(`attr`, `content`)
+    .should(`equal`, data.static.meta)
+  cy.getTestElement(`noscript`).should(`have.text`, data.static.noscript)
+  cy.getTestElement(`style`).should(`contain`, data.static.style)
+  cy.getTestElement(`link`)
+    .invoke(`attr`, `href`)
+    .should(`equal`, data.static.link)
+
+  // Navigate to a different page via Gatsby Link
+  cy.getTestElement(`gatsby-link`).click()
+
+  // Validate data on navigated-to page
+  cy.getTestElement(`base`)
+    .invoke(`attr`, `href`)
+    .should(`equal`, data.queried.base)
+  cy.getTestElement(`title`).should(`have.text`, data.queried.title)
+  cy.getTestElement(`meta`)
+    .invoke(`attr`, `content`)
+    .should(`equal`, data.queried.meta)
+  cy.getTestElement(`noscript`).should(`have.text`, data.queried.noscript)
+  cy.getTestElement(`style`).should(`contain`, data.queried.style)
+  cy.getTestElement(`link`)
+    .invoke(`attr`, `href`)
+    .should(`equal`, data.queried.link)
+
+  // Navigate back to original page via Gatsby Link
+  cy.getTestElement(`gatsby-link`).click()
+
+  // Validate data is same as initial load
+  cy.getTestElement(`base`)
+    .invoke(`attr`, `href`)
+    .should(`equal`, data.static.base)
+  cy.getTestElement(`title`).should(`have.text`, data.static.title)
+  cy.getTestElement(`meta`)
+    .invoke(`attr`, `content`)
+    .should(`equal`, data.static.meta)
+  cy.getTestElement(`noscript`).should(`have.text`, data.static.noscript)
+  cy.getTestElement(`style`).should(`contain`, data.static.style)
+  cy.getTestElement(`link`)
+    .invoke(`attr`, `href`)
+    .should(`equal`, data.static.link)
+})

e2e-tests/development-runtime/cypress/integration/head-function-export/warnings.js

@@ -0,0 +1,28 @@
+import { VALID_NODE_NAMES } from "gatsby/cache-dir/head/constants"
+import { page } from "../../../shared-data/head-function-export.js"
+
+describe(`head function export should warn`, () => {
+  beforeEach(() => {
+    cy.visit(page.warnings, {
+      onBeforeLoad(win) {
+        cy.stub(win.console, `warn`).as(`consoleWarn`)
+      },
+    })
+  })
+
+  it(`for elements that belong in the body`, () => {
+    cy.get(`@consoleWarn`).should(
+      `be.calledWith`,
+      `<h1> is not a valid head element. Please use one of the following: ${VALID_NODE_NAMES.join(
+        `, `
+      )}`
+    )
+  })
+
+  it(`for scripts that could use the script component`, () => {
+    cy.get(`@consoleWarn`).should(
+      `be.calledWith`,
+      `Do not add scripts here. Please use the <Script> component in your page template instead. For more info see: https://www.gatsbyjs.com/docs/reference/built-in-components/gatsby-script/`
+    )
+  })
+})

e2e-tests/development-runtime/gatsby-config.js

@@ -1,3 +1,7 @@
+const {
+  data: headFunctionExportData,
+} = require(`./shared-data/head-function-export.js`)
+
 /**
  * @type {import('gatsby').GatsbyConfig}
  */
@@ -8,6 +12,8 @@ module.exports = {
     social: {
       twitter: `kylemathews`,
     },
+    // Separate to avoid needing to change other tests that rely on site metadata
+    headFunctionExport: headFunctionExportData.queried,
   },
   graphqlTypegen: true,
   flags: {

e2e-tests/development-runtime/shared-data/head-function-export.js

@@ -0,0 +1,31 @@
+const path = `/head-function-export`
+
+const page = {
+  basic: `${path}/basic/`,
+  pageQuery: `${path}/page-query/`,
+  reExport: `${path}/re-exported-function/`,
+  staticQuery: `${path}/static-query-component/`,
+  warnings: `${path}/warnings/`,
+  allProps: `${path}/all-props/`,
+}
+
+const data = {
+  static: {
+    base: `http://localhost:8000`,
+    title: `Ella Fitzgerald's Page`,
+    meta: `Ella Fitzgerald`,
+    noscript: `You take romance - I will take Jell-O!`,
+    style: `rebeccapurple`,
+    link: `/used-by-head-function-export-basic.css`,
+  },
+  queried: {
+    base: `http://localhost:8000`,
+    title: `Nat King Cole's Page`,
+    meta: `Nat King Cole`,
+    noscript: `There is just one thing I cannot figure out. My income tax!`,
+    style: `blue`,
+    link: `/used-by-head-function-export-query.css`,
+  },
+}
+
+module.exports = { page, data }

e2e-tests/development-runtime/src/components/head-function-export.js

@@ -0,0 +1,67 @@
+import * as React from "react"
+import { useStaticQuery, graphql } from "gatsby"
+import { data } from "../../shared-data/head-function-export.js"
+
+function HeadComponent({ children }) {
+  const data = useStaticQuery(graphql`
+    query SiteMetaDataStaticQuery {
+      site {
+        siteMetadata {
+          headFunctionExport {
+            base
+            title
+            meta
+            noscript
+            style
+            link
+          }
+        }
+      }
+    }
+  `)
+
+  const { base, title, meta, noscript, style, link } =
+    data?.site?.siteMetadata?.headFunctionExport || {}
+
+  return (
+    <>
+      <base data-testid="base" href={base} />
+      <title data-testid="title">{title}</title>
+      <meta data-testid="meta" name="author" content={meta} />
+      <noscript data-testid="noscript">{noscript}</noscript>
+      <style data-testid="style">
+        {`
+          h1 {
+            color: ${style};
+          }
+        `}
+      </style>
+      <link data-testid="link" href={link} rel="stylesheet" />
+      {children}
+    </>
+  )
+}
+
+function head() {
+  const { base, title, meta, noscript, style, link } = data.static
+
+  return (
+    <>
+      <base data-testid="base" href={base} />
+      <title data-testid="title">{title}</title>
+      <meta data-testid="meta" name="author" content={meta} />
+      <noscript data-testid="noscript">{noscript}</noscript>
+      <style data-testid="style">
+        {`
+          h1 {
+            color: ${style};
+          }
+        `}
+      </style>
+      <link data-testid="link" href={link} rel="stylesheet" />
+    </>
+  )
+}
+
+export { head }
+export default HeadComponent

e2e-tests/development-runtime/src/pages/head-function-export/all-props.js

@@ -0,0 +1,41 @@
+import * as React from "react"
+
+export default function HeadFunctionExportAllProps(props) {
+  return (
+    <>
+      <h1>
+        I test usage for the head function export to make sure all props are
+        received
+      </h1>
+      <pre>{JSON.stringify(props, null, 2)}</pre>
+    </>
+  )
+}
+
+export function head(props) {
+  const { location, pageContext, pageResources, params, path, uri } =
+    props || {}
+
+  return (
+    <>
+      <meta
+        data-testid="location.origin"
+        name="location.origin"
+        content={location?.origin}
+      />
+      <meta
+        data-testid="pageContext"
+        name="pageContext"
+        content={pageContext}
+      />
+      <meta
+        data-testid="pageResources.page.componentChunkName"
+        name="pageResources.page.componentChunkName"
+        content={pageResources?.page?.componentChunkName}
+      />
+      <meta data-testid="params" name="params" content={params} />
+      <meta data-testid="path" name="path" content={path} />
+      <meta data-testid="uri" name="uri" content={uri} />
+    </>
+  )
+}

e2e-tests/development-runtime/src/pages/head-function-export/basic.js

@@ -0,0 +1,36 @@
+import * as React from "react"
+import { Link } from "gatsby"
+import { data } from "../../../shared-data/head-function-export"
+
+export default function HeadFunctionExportBasic() {
+  return (
+    <>
+      <h1>I test basic usage for the head function export</h1>
+      <p>Some other words</p>
+      <Link data-testid="gatsby-link" to="/head-function-export/page-query">
+        Navigate to page-query via Gatsby Link
+      </Link>
+    </>
+  )
+}
+
+export function head() {
+  const { base, title, meta, noscript, style, link } = data.static
+
+  return (
+    <>
+      <base data-testid="base" href={base} />
+      <title data-testid="title">{title}</title>
+      <meta data-testid="meta" name="author" content={meta} />
+      <noscript data-testid="noscript">{noscript}</noscript>
+      <style data-testid="style">
+        {`
+          h1 {
+            color: ${style};
+          }
+        `}
+      </style>
+      <link data-testid="link" href={link} rel="stylesheet" />
+    </>
+  )
+}