Better error message for MDX html field in development

[fionawhim]

Summary

Currently, if you query the html field of gatsby-plugin-mdx GraphQL nodes in development, you get the following errors in the console and the GraphQL output.

ReferenceError: window is not defined
    at evalmachine.<anonymous>:5:41
    at evalmachine.<anonymous>:794:10
    at ContextifyScript.Script.runInContext (vm.js:59:29)
    at ContextifyScript.Script.runInNewContext (vm.js:65:15)
    at module.exports (/Users/fin/Source/my-themed-blog/node_modules/eval/eval.js:73:12)
    at afterEmit (/Users/fin/Source/my-themed-blog/node_modules/gatsby-plugin-mdx/utils/render-html.js:81:22)
…

and:

gatsby-plugin-mdx: renderMdxBody was unavailable when rendering html.
>> This is a bug.

This can be confusing, whether you’re mistakenly using html in a web page (it should be body), or when you’re testing out in development a query for the RSS feed or some place where you mean to use body.

The plugin should either throw a more explicit error, or instead return an obviously incorrect, but helpful value for html.

Basic example

For example, the query:

query MyQuery {
  allMdx {
    nodes {
      html
    }
  }
}

could return:

{
  "allMdx": {
    "nodes": [{
       "html": "<strong>WARNING:</strong> The <code>html</code> field cannot be used in development. Did you mean <code>body</code>? (If you need this node’s HTML content for a non-browser output, such as an RSS feed, you can this query in production mode.)"
    }]
  }

This message is not a GraphQL error, which means you can still see the rest of any query you’re working on work. It also contains some HTML, so you can use dev mode to check any encoding or escaping/unescaping you need to do.

Motivation

This is a confusing error message both for people who tried html when they should have used body (#16706) and for people who knew they wanted html but were confused why the query they were testing errored out (#17175).

[gatsbot]

Hiya!

This issue has gone quiet. Spooky quiet. 👻

We get a lot of issues, so we currently close issues after 30 days of inactivity. It’s been at least 20 days since the last update here.

If we missed this issue or if you want to keep it open, please reply here. You can also add the label "not stale" to keep this issue open!

As a friendly reminder: the best way to see this issue, or any other, fixed is to open a Pull Request. Check out gatsby.dev/contribute for more information about opening PRs, triaging issues, and contributing!

Thanks for being a part of the Gatsby community! 💪💜

[sidharthachatterjee]

I understand the motivation here but I'm not sure if returning back placeholder text like you've described is a good idea.

This could be something a user could very easily miss during development. What do you think?

However, I do think that we could display a more descriptive error in the console.

[marcysutton]

This seems like something that would benefit from a structured error message, as related to #15019.