MDX error messages

[willcrichton]

Hey, I'm evaluating MDX for potential use as an alternative syntax for Nota, my academic paper framework. One big issue that I've seen so far is how MDX handles certain kinds of errors.

Let's say I forget an import for a custom component, such as:

import {Foo} from "foo";

<Foo />
<Bar /> <-- uh oh!

From what I understand reading the output, MDX will resolve Foo to foo.Foo, while Bar will just be assumed to be an unresolved/external global and left as is. Then when React tries to render the page, it gives the error:

The error isn't helpful since it just says "somewhere in the document, you have a null element." Are there ways to improve this? Either during the MDX pass to flag such issues, or better source-mapping so React can point to a specific spot where the error arises?

[ChristianMurphy]

better source-mapping so React can point to a specific spot where the error arises?

@willcrichton you may want to try out MDX 2 (currently at release candidate 1 https://github.com/mdx-js/mdx/releases/tag/2.0.0-rc.1), which includes better source mapping.

during the MDX pass to flag such issues

As you noted, this error is not coming from MDX, it comes from React (or could come from Preact or Vue).
I'd lean against trying to model these errors in MDX itself, this is better suited for https://github.com/mdx-js/eslint-mdx (which I believe may already be able to do this) and/or the framework itself (React in your case) with source maps.

[willcrichton]

Thanks @ChristianMurphy. I am using MDX 2 via esbuild with sourcemap: true. Do I need to do something else to enable the improved source maps?

[ChristianMurphy]

Using MDX 2 RC 1 or newer? Improved source maps were part of #1755

[willcrichton]

Yes, installed via "@mdx-js/esbuild": "^2.0.0-rc.1".

[wooorm]

I'm evaluating MDX for potential use as an alternative syntax

What is the other syntax?

From what I understand […] MDX will resolve Foo to foo.Foo, while Bar will just be assumed to be an unresolved/external global and left as is.

Not exactly. See How MDX works for the output. Bar can be passed or provided.

Either during the MDX pass to flag such issues, or better source-mapping so React can point to a specific spot where the error arises?

Unfortunately it is not known at compile time whether this is an issue.

---

In MDX 1, there is an error. It works something like this:

const _components = Object.assign({
  p: "p",
  // …
  Bar: () => console.warn('`Bar` is not defined')
}, props.components)

This is a) not consistent with react and similar, because they throw for missing components, b) doesn’t work well with objects. In JSX you can use object access notation like this: <Bar /> to use the whole Bar, <Bar.Baz /> to get the baz component from Bar.
It becomes a quite complex “merge” to add these fallbacks for different cases:

• What if Bar is not given?
• What if Bar is given but Bar.baz isn’t

JSX dot notation isn’t limited to one component on an object, but can be long: <com.acme.theme.heading /> or so, and the intermediate objects could be components themselves.

---

I can see a couple ways to improve this:

• We can add error fallback components for things like Bar:

  Bar: () => throw new error('`Bar` is not defined')

  Downside: doesn’t work for Bar.Baz
• We already typically compile to the automatic production JSX runtime (_jsx) (though the classic runtime is also supported). We could support the _jsxDEV runtime. This passes more information to React, as in:

  _jsxDEV(Bar, {}, void 0, false, {
    fileName: '/Users/.../example.mdx',
    lineNumber: 9,
    columnNumber: 59
  }, this)

  Downside: How to detect development mode? And: this is somewhat limited info and React doesn’t display most of it:

  Warning: React.jsx: type is invalid -- expected a string (for built-in components) or a class/function (for composite components) but got: undefined. You likely forgot to export your component from the file it's defined in, or you might have mixed up default and named imports.
  
  Check your code at example.mdx:9.
      at MDXContent
  /Users/.../node_modules/react-dom/cjs/react-dom-server-legacy.node.development.js:5606
        throw Error( "Element type is invalid: expected a string (for built-in components) or a class/function (for composite components) but got: " + (type == null ? type : typeof type) + "." + info );
              ^
  
  Error: Element type is invalid: expected a string (for built-in components) or a class/function (for composite components) but got: undefined. You likely forgot to export your component from the file it's defined in, or you might have mixed up default and named imports.
      ...
  

  This also still errors, in a rather garbled way, for dot notation:

  }, this), "\n", /*#__PURE__*/_jsxDEV(Bar.baz, {}, void 0, false, {
                                           ^
  
  TypeError: Cannot read properties of undefined (reading 'baz')
  at _createMdxContent (file:///Users/.../output.js:37:48)
  

• We can our own runtime existence checks:

  const _components = Object.assign({h1: "h1"}, props.components),
    {Bar} = _components;
  if (!Bar) _createError('Bar')
  if (!Bar.Baz) _createError('Bar.Baz')
  function _createError(name) { throw new Error('`' + name + '` is not defined') }

  Downside: How to detect dev mode? And: might generate a lot of code.
  But, what if we essentially pack our own “dev” runtime?

  if (!Bar) _createError('Bar', '3:1-3:8')
  if (!Bar.Baz) _createError('Bar.Baz', '4:1-5:12')
  function _createError(name, range) { throw new Error('`' + name + '` is not defined in `/Users/.../example.mdx` at `' + range + '`, please import, pass, or provide it') }

  I think all these references to the file system might be a security problem by default and too much for production, but it sounds like it could work?

[willcrichton]

The baseline syntax is just JSX. But I'd like to make a Markdown-flavored syntax that is much more concise and compiles into JSX. It seems like MDX with a bunch of plugins might be a good fit.

Thanks for the thorough exploration of some designs! Yet another alternative might be a hook in the MDX API that contains information about which custom elements were not found. The default behavior is to add them to the components list, but the hook could alternatively just halt compilation with source-mapped information about which elements were not found and where.

More broadly, I would prefer a compile-time solution to a run-time solution since I'd like to validate these documents as much as possible before code generation.

[wooorm]

I would prefer a compile-time solution

It’s not possible to do this at compile time because arbitrary components can be passed and provided at runtime.
This is rather important behavior of MDX—most folks use it, they pass and provide components—so I don’t see such a hook making a lot of sense. Especially because, if you have a know list of allowed references, you can write a plugin to check whether components match that list yourself already. See Extending MDX.

[wooorm]

I’ve added my last proposal with a development option to xdm@3.2.0: https://github.com/wooorm/xdm/releases/tag/3.2.0.
It can be added to mdx-js/mdx in the next rc/the actual release. I want to be a bit conservative and slow with MDX RC releases.

[willcrichton]

Great, I will try it out. Also thanks for all your hard work on this ecosystem! I've been very impressed with the architecture / code quality / documentation of the packages in micromark, remark, unified, so on.

[wooorm]

thank you! :)