.eslintrc.js

@@ -105,11 +105,18 @@ module.exports = {
           "error",
           { ignoreParameters: true },
         ],
-        // This rule tries to ensure we use camelCase for all variables, properties
-        // functions, etc. However, it is not always possible to ensure properties
-        // are camelCase. Specifically we have `node.__gatsby_resolve` which breaks
-        // this rule. This allows properties to be whatever they need to be.
-        "@typescript-eslint/camelcase": ["error", { properties: "never" }],
+        "@typescript-eslint/camelcase": [
+          "error",
+          {
+            // This rule tries to ensure we use camelCase for all variables, properties
+            // functions, etc. However, it is not always possible to ensure properties
+            // are camelCase. Specifically we have `node.__gatsby_resolve` which breaks
+            // this rule. This allows properties to be whatever they need to be.
+            properties: "never",
+            // Allow unstable api's to use `unstable_`, which is easier to grep
+            allow: ["^unstable_"],
+          },
+        ],
         // This rule tries to prevent using `require()`. However in node code,
         // there are times where this makes sense. And it specifically is causing
         // problems in our tests where we often want this functionality for module

docs/docs/configuring-usage-with-plugin-options.md

@@ -28,7 +28,7 @@ For example, `gatsby-plugin-console-log` can access the `message` in order to lo
 ```javascript:title=plugins/gatsby-plugin-console-log/gatsby-node.js
 exports.onPreInit = (_, pluginOptions) => {
   console.log(
-    `logging: "${pluginOptions.message || `default message`}" to the console` // highlight-line
+    `logging: "${pluginOptions.message}" to the console` // highlight-line
   )
 }
 ```
@@ -54,6 +54,24 @@ The following table lists possible options values and an example plugin that mak
 
 **Note**: Themes (which are a type of plugin) are able to receive options from a site's `gatsby-config` to be used in its `gatsby-config` in order to allow themes to be composed together. This is done by exporting the `gatsby-config` as a function instead of an object. You can see an example of this in the [`gatsby-theme-blog`](https://github.com/gatsbyjs/themes/tree/master/packages/gatsby-theme-blog) and [`gatsby-theme-blog-core`](https://github.com/gatsbyjs/themes/tree/master/packages/gatsby-theme-blog-core) repositories. Plugins are not capable of this functionality.
 
+## How to validate options
+
+In order to make configuration easier for users, plugins can optionally define a [Joi](https://joi.dev) schema to enforce data types for each option using the [`pluginOptionsSchema` API](/docs/node-apis/#pluginOptionsSchema) in `gatsby-node.js`. When users of the plugin pass in configuration options, Gatsby will validate that the options match the schema.
+
+For example, here is what the schema for `gatsby-plugin-console-log` looks like:
+
+```javascript:title=plugins/gatsby-plugin-console-log/gatsby-node.js
+exports.pluginOptionsSchema = ({ Joi }) => {
+  return Joi.object({
+    optionA: Joi.boolean().required(),
+    message: Joi.string().required().default(`default message`),
+    optionB: Joi.boolean(),
+  })
+}
+```
+
+This ensures users pass a boolean to `optionA` and `optionB`, and a string to `message`. If they pass options that do not match the schema, the validation will show an error when they run `gatsby develop`. It also defaults the `message` option to "default message" in case users do not pass their own.
+
 ## Additional resources
 
 - [Example Gatsby site using plugin options with a local plugin](https://github.com/gatsbyjs/gatsby/tree/master/examples/using-plugin-options)

e2e-tests/development-runtime/content/error-recovery/page-query.json

@@ -0,0 +1,4 @@
+{
+  "selector": "page-query",
+  "hasError": false
+}

e2e-tests/development-runtime/content/error-recovery/static-query.json

@@ -0,0 +1,4 @@
+{
+  "selector": "static-query",
+  "hasError": false
+}

e2e-tests/development-runtime/cypress/integration/hot-reloading/error-handling/compile-error.js

@@ -0,0 +1,41 @@
+before(() => {
+  cy.exec(
+    `npm run update -- --file src/pages/error-handling/compile-error.js --restore`
+  )
+})
+
+after(() => {
+  cy.exec(
+    `npm run update -- --file src/pages/error-handling/compile-error.js --restore`
+  )
+})
+
+const errorPlaceholder = `// compile-error`
+const errorReplacement = `a b`
+
+describe(`testing error overlay and ability to automatically recover from webpack compile errors`, () => {
+  it(`displays content initially (no errors yet)`, () => {
+    cy.visit(`/error-handling/compile-error/`).waitForRouteChange()
+    cy.getTestElement(`hot`).invoke(`text`).should(`contain`, `Working`)
+  })
+
+  it(`displays error with overlay on compilation errors`, () => {
+    cy.exec(
+      `npm run update -- --file src/pages/error-handling/compile-error.js --replacements "${errorPlaceholder}:${errorReplacement}" --exact`
+    )
+
+    cy.getOverlayIframe().contains(`Failed to compile`)
+    cy.getOverlayIframe().contains(`Parsing error: Unexpected token`)
+    cy.screenshot()
+  })
+
+  it(`can recover without need to refresh manually`, () => {
+    cy.exec(
+      `npm run update -- --file src/pages/error-handling/compile-error.js --replacements "Working:Updated" --replacements "${errorReplacement}:${errorPlaceholder}" --exact`
+    )
+
+    cy.getTestElement(`hot`).invoke(`text`).should(`contain`, `Updated`)
+    cy.assertNoOverlayIframe()
+    cy.screenshot()
+  })
+})

e2e-tests/development-runtime/cypress/integration/hot-reloading/error-handling/page-query-result-runtime-error.js

@@ -0,0 +1,69 @@
+Cypress.on("uncaught:exception", (err, runnable) => {
+  // returning false here prevents Cypress from
+  // failing the test
+  return false
+})
+
+before(() => {
+  cy.exec(
+    `npm run update -- --file content/error-recovery/page-query.json --restore`
+  )
+  cy.exec(
+    `npm run update -- --file src/pages/error-handling/page-query-result-runtime-error.js --restore`
+  )
+})
+
+after(() => {
+  cy.exec(
+    `npm run update -- --file content/error-recovery/page-query.json --restore`
+  )
+  cy.exec(
+    `npm run update -- --file src/pages/error-handling/page-query-result-runtime-error.js --restore`
+  )
+})
+
+const errorPlaceholder = `false`
+const errorReplacement = `true`
+
+describe(`testing error overlay and ability to automatically recover runtime errors cause by content changes (page queries variant)`, () => {
+  it(`displays content initially (no errors yet)`, () => {
+    cy.visit(
+      `/error-handling/page-query-result-runtime-error/`
+    ).waitForRouteChange()
+    cy.getTestElement(`hot`).invoke(`text`).should(`contain`, `Working`)
+    cy.getTestElement(`results`)
+      .invoke(`text`)
+      .should(`contain`, `"hasError": false`)
+  })
+
+  it(`displays error with overlay on runtime errors`, () => {
+    cy.exec(
+      `npm run update -- --file content/error-recovery/page-query.json  --replacements "${errorPlaceholder}:${errorReplacement}" --exact`
+    )
+
+    // that's the exact error we throw and we expect to see that
+    cy.getOverlayIframe().contains(`Page query results caused runtime error`)
+    // contains details
+    cy.getOverlayIframe().contains(
+      `src/pages/error-handling/page-query-result-runtime-error.js`
+    )
+    cy.screenshot()
+  })
+
+  it(`can recover without need to refresh manually`, () => {
+    cy.exec(
+      `npm run update -- --file content/error-recovery/page-query.json  --replacements "${errorReplacement}:${errorPlaceholder}" --exact`
+    )
+    cy.exec(
+      `npm run update -- --file src/pages/error-handling/page-query-result-runtime-error.js --replacements "Working:Updated" --exact`
+    )
+
+    cy.getTestElement(`hot`).invoke(`text`).should(`contain`, `Updated`)
+    cy.getTestElement(`results`)
+      .invoke(`text`)
+      .should(`contain`, `"hasError": false`)
+
+    cy.assertNoOverlayIframe()
+    cy.screenshot()
+  })
+})

e2e-tests/development-runtime/cypress/integration/hot-reloading/error-handling/query-validation-error.js

@@ -0,0 +1,45 @@
+before(() => {
+  cy.exec(
+    `npm run update -- --file src/pages/error-handling/query-validation-error.js --restore`
+  )
+})
+
+after(() => {
+  cy.exec(
+    `npm run update -- --file src/pages/error-handling/query-validation-error.js --restore`
+  )
+})
+
+const errorPlaceholder = `# query-validation-error`
+const errorReplacement = `fieldThatDoesNotExistOnSiteMapType`
+
+describe(`testing error overlay and ability to automatically recover from query extraction validation errors`, () => {
+  it(`displays content initially (no errors yet)`, () => {
+    cy.visit(`/error-handling/query-validation-error/`).waitForRouteChange()
+    cy.getTestElement(`hot`).invoke(`text`).should(`contain`, `Working`)
+  })
+
+  it(`displays error with overlay on compilation errors`, () => {
+    cy.exec(
+      `npm run update -- --file src/pages/error-handling/query-validation-error.js --replacements "${errorPlaceholder}:${errorReplacement}" --exact`
+    )
+
+    cy.getOverlayIframe().contains(`Failed to compile`)
+    cy.getOverlayIframe().contains(`There was an error in your GraphQL query`)
+    // make sure we mark location
+    cy.getOverlayIframe().contains(
+      `src/pages/error-handling/query-validation-error.js`
+    )
+    cy.screenshot()
+  })
+
+  it(`can recover without need to refresh manually`, () => {
+    cy.exec(
+      `npm run update -- --file src/pages/error-handling/query-validation-error.js --replacements "Working:Updated" --replacements "${errorReplacement}:${errorPlaceholder}" --exact`
+    )
+
+    cy.getTestElement(`hot`).invoke(`text`).should(`contain`, `Updated`)
+    cy.assertNoOverlayIframe()
+    cy.screenshot()
+  })
+})

e2e-tests/development-runtime/cypress/integration/hot-reloading/error-handling/runtime-error.js

@@ -0,0 +1,48 @@
+Cypress.on("uncaught:exception", (err, runnable) => {
+  // returning false here prevents Cypress from
+  // failing the test
+  return false
+})
+
+before(() => {
+  cy.exec(
+    `npm run update -- --file src/pages/error-handling/runtime-error.js --restore`
+  )
+})
+
+after(() => {
+  cy.exec(
+    `npm run update -- --file src/pages/error-handling/runtime-error.js --restore`
+  )
+})
+
+const errorPlaceholder = `// runtime-error`
+const errorReplacement = `window.a.b.c.d.e.f.g()`
+
+describe(`testing error overlay and ability to automatically recover from runtime errors`, () => {
+  it(`displays content initially (no errors yet)`, () => {
+    cy.visit(`/error-handling/runtime-error/`).waitForRouteChange()
+    cy.getTestElement(`hot`).invoke(`text`).should(`contain`, `Working`)
+  })
+
+  it(`displays error with overlay on runtime errors`, () => {
+    cy.exec(
+      `npm run update -- --file src/pages/error-handling/runtime-error.js --replacements "${errorPlaceholder}:${errorReplacement}" --exact`
+    )
+
+    cy.getOverlayIframe().contains(`Cannot read property`)
+    // contains details
+    cy.getOverlayIframe().contains(`src/pages/error-handling/runtime-error.js`)
+    cy.screenshot()
+  })
+
+  it(`can recover without need to refresh manually`, () => {
+    cy.exec(
+      `npm run update -- --file src/pages/error-handling/runtime-error.js --replacements "Working:Updated" --replacements "${errorReplacement}:${errorPlaceholder}" --exact`
+    )
+
+    cy.getTestElement(`hot`).invoke(`text`).should(`contain`, `Updated`)
+    cy.assertNoOverlayIframe()
+    cy.screenshot()
+  })
+})

e2e-tests/development-runtime/cypress/integration/hot-reloading/error-handling/static-query-result-runtime-error.js

@@ -0,0 +1,69 @@
+Cypress.on("uncaught:exception", (err, runnable) => {
+  // returning false here prevents Cypress from
+  // failing the test
+  return false
+})
+
+before(() => {
+  cy.exec(
+    `npm run update -- --file content/error-recovery/static-query.json --restore`
+  )
+  cy.exec(
+    `npm run update -- --file src/pages/error-handling/static-query-result-runtime-error.js --restore`
+  )
+})
+
+after(() => {
+  cy.exec(
+    `npm run update -- --file content/error-recovery/static-query.json --restore`
+  )
+  cy.exec(
+    `npm run update -- --file src/pages/error-handling/static-query-result-runtime-error.js --restore`
+  )
+})
+
+const errorPlaceholder = `false`
+const errorReplacement = `true`
+
+describe(`testing error overlay and ability to automatically recover from runtime errors (static queries variant)`, () => {
+  it(`displays content initially (no errors yet)`, () => {
+    cy.visit(
+      `/error-handling/static-query-result-runtime-error/`
+    ).waitForRouteChange()
+    cy.getTestElement(`hot`).invoke(`text`).should(`contain`, `Working`)
+    cy.getTestElement(`results`)
+      .invoke(`text`)
+      .should(`contain`, `"hasError": false`)
+  })
+
+  it(`displays error with overlay on runtime errors`, () => {
+    cy.exec(
+      `npm run update -- --file content/error-recovery/static-query.json  --replacements "${errorPlaceholder}:${errorReplacement}" --exact`
+    )
+
+    // that's the exact error we throw and we expect to see that
+    cy.getOverlayIframe().contains(`Static query results caused runtime error`)
+    // contains details
+    cy.getOverlayIframe().contains(
+      `src/pages/error-handling/static-query-result-runtime-error.js`
+    )
+    cy.screenshot()
+  })
+
+  it(`can recover without need to refresh manually`, () => {
+    cy.exec(
+      `npm run update -- --file content/error-recovery/static-query.json  --replacements "${errorReplacement}:${errorPlaceholder}" --exact`
+    )
+    cy.exec(
+      `npm run update -- --file src/pages/error-handling/static-query-result-runtime-error.js --replacements "Working:Updated" --exact`
+    )
+
+    cy.getTestElement(`hot`).invoke(`text`).should(`contain`, `Updated`)
+    cy.getTestElement(`results`)
+      .invoke(`text`)
+      .should(`contain`, `"hasError": false`)
+
+    cy.assertNoOverlayIframe()
+    cy.screenshot()
+  })
+})

e2e-tests/development-runtime/cypress/support/commands.js

@@ -24,7 +24,7 @@ Cypress.Commands.add(`lifecycleCallOrder`, expectedActionCallOrder =>
     if (expectedActionCallOrderLength > actionsLength) {
       return false
     }
-    
+
     let prevActionIndex = -1
     for (let i = 0; i < actionsLength; i += 1) {
       const nextActionIndex = prevActionIndex + 1
@@ -81,6 +81,29 @@ Cypress.Commands.add(
   }
 )
 
-Cypress.Commands.add(`assertRoute`, (route) => {
+Cypress.Commands.add(`assertRoute`, route => {
   cy.url().should(`equal`, `${window.location.origin}${route}`)
 })
+
+// react-error-overlay is iframe, so this is just convenience helper
+// https://www.cypress.io/blog/2020/02/12/working-with-iframes-in-cypress/#custom-command
+Cypress.Commands.add(`getOverlayIframe`, () => {
+  // get the iframe > document > body
+  // and retry until the body element is not empty
+  return (
+    cy
+      .get(`iframe`, { log: true, timeout: 150000 })
+      .its(`0.contentDocument.body`)
+      .should(`not.be.empty`)
+      // wraps "body" DOM element to allow
+      // chaining more Cypress commands, like ".find(...)"
+      // https://on.cypress.io/wrap
+      .then(cy.wrap, { log: true })
+  )
+})
+
+Cypress.Commands.add(`assertNoOverlayIframe`, () => {
+  // get the iframe > document > body
+  // and retry until the body element is not empty
+  return cy.get(`iframe`, { log: true, timeout: 15000 }).should(`not.exist`)
+})

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

@@ -29,6 +29,7 @@ module.exports = {
     },
     `gatsby-source-fake-data`,
     `gatsby-transformer-sharp`,
+    `gatsby-transformer-json`,
     {
       resolve: `gatsby-transformer-remark`,
       options: {