Add support JSX development runtime

The JSX dev runtime exposes more debugging information to users. For
example, React exposes positional information through React Devtools.

Although GH-2035 started off as an issue to support the `__source` prop, I
have refrained from actually supporting the `__source` prop, as it’s
specific to React. The automatic dev runtime supports this information
without patching props.

Closes GH-2035.
Closes GH-2045.

Reviewed-by: Titus Wormer <[email protected]>

Author: remcohaszing

packages/mdx/lib/core.js

@@ -125,7 +125,7 @@ export function createProcessor(options = {}) {
     .use(recmaJsxRewrite, {development, providerImportSource, outputFormat})
 
   if (!jsx) {
-    pipeline.use(recmaJsxBuild, {outputFormat})
+    pipeline.use(recmaJsxBuild, {development, outputFormat})
   }
 
   pipeline.use(recmaStringify, {SourceMapGenerator}).use(recmaPlugins || [])

packages/mdx/lib/plugin/recma-jsx-build.js

@@ -1,5 +1,6 @@
 /**
  * @typedef {import('estree-jsx').Program} Program
+ * @typedef {import('estree-util-build-jsx').BuildJsxOptions} BuildJsxOptions
  *
  * @typedef RecmaJsxBuildOptions
  * @property {'program'|'function-body'} [outputFormat='program']
@@ -15,13 +16,13 @@ import {toIdOrMemberExpression} from '../util/estree-util-to-id-or-member-expres
  * A plugin to build JSX into function calls.
  * `estree-util-build-jsx` does all the work for us!
  *
- * @type {import('unified').Plugin<[RecmaJsxBuildOptions]|[], Program>}
+ * @type {import('unified').Plugin<[BuildJsxOptions & RecmaJsxBuildOptions?], Program>}
  */
 export function recmaJsxBuild(options = {}) {
-  const {outputFormat} = options
+  const {development, outputFormat} = options
 
-  return (tree) => {
-    buildJsx(tree)
+  return (tree, file) => {
+    buildJsx(tree, {development, filePath: file.history[0]})
 
     // When compiling to a function body, replace the import that was just
     // generated, and get `jsx`, `jsxs`, and `Fragment` from `arguments[0]`
@@ -31,7 +32,7 @@ export function recmaJsxBuild(options = {}) {
       tree.body[0] &&
       tree.body[0].type === 'ImportDeclaration' &&
       typeof tree.body[0].source.value === 'string' &&
-      /\/jsx-runtime$/.test(tree.body[0].source.value)
+      /\/jsx-(dev-)?runtime$/.test(tree.body[0].source.value)
     ) {
       tree.body[0] = {
         type: 'VariableDeclaration',

packages/mdx/lib/util/resolve-evaluate-options.js

@@ -4,10 +4,12 @@
  * @typedef RunnerOptions
  * @property {*} Fragment
  *   Symbol to use for fragments.
- * @property {*} jsx
- *   Function to generate an element with static children.
- * @property {*} jsxs
- *   Function to generate an element with dynamic children.
+ * @property {*} [jsx]
+ *   Function to generate an element with static children in production mode.
+ * @property {*} [jsxs]
+ *   Function to generate an element with dynamic children in production mode.
+ * @property {*} [jsxDEV]
+ *   Function to generate an element in development mode.
  * @property {*} [useMDXComponents]
  *   Function to get `MDXComponents` from context.
  *
@@ -23,18 +25,24 @@
  * @returns {{compiletime: ProcessorOptions, runtime: RunnerOptions}}
  */
 export function resolveEvaluateOptions(options) {
-  const {Fragment, jsx, jsxs, useMDXComponents, ...rest} = options || {}
+  const {development, Fragment, jsx, jsxs, jsxDEV, useMDXComponents, ...rest} =
+    options || {}
 
   if (!Fragment) throw new Error('Expected `Fragment` given to `evaluate`')
-  if (!jsx) throw new Error('Expected `jsx` given to `evaluate`')
-  if (!jsxs) throw new Error('Expected `jsxs` given to `evaluate`')
+  if (development) {
+    if (!jsxDEV) throw new Error('Expected `jsxDEV` given to `evaluate`')
+  } else {
+    if (!jsx) throw new Error('Expected `jsx` given to `evaluate`')
+    if (!jsxs) throw new Error('Expected `jsxs` given to `evaluate`')
+  }
 
   return {
     compiletime: {
       ...rest,
+      development,
       outputFormat: 'function-body',
       providerImportSource: useMDXComponents ? '#' : undefined
     },
-    runtime: {Fragment, jsx, jsxs, useMDXComponents}
+    runtime: {Fragment, jsx, jsxs, jsxDEV, useMDXComponents}
   }
 }

packages/mdx/test/compile.js

@@ -543,6 +543,22 @@ test('compile', async () => {
   )
   console.log('\nnote: the preceding warning is expected!\n')
 
+  const developmentSourceNode = (
+    await run(
+      compileSync(
+        {value: '<div />', path: 'path/to/file.js'},
+        {development: true}
+      ).value
+    )
+  )({})
+  assert.equal(
+    // @ts-expect-error React attaches source information on this property,
+    // but it’s private and untyped.
+    developmentSourceNode._source,
+    {fileName: 'path/to/file.js', lineNumber: 1, columnNumber: 1},
+    'should expose source information in the automatic jsx dev runtime'
+  )
+
   try {
     renderToStaticMarkup(
       React.createElement(await run(compileSync('<X />', {development: true})))
@@ -1503,6 +1519,40 @@ test('MDX (ESM)', async () => {
     '<div style="color:red"><p>a</p></div>',
     'should support rexporting the default export, and other things, from a source'
   )
+
+  assert.equal(
+    compileSync({value: '<X />', path: 'path/to/file.js'}, {development: true})
+      .value,
+    [
+      '/*@jsxRuntime automatic @jsxImportSource react*/',
+      'import {jsxDEV as _jsxDEV} from "react/jsx-dev-runtime";',
+      'function _createMdxContent(props) {',
+      '  const {X} = props.components || ({});',
+      '  if (!X) _missingMdxReference("X", true, "1:1-1:6");',
+      '  return _jsxDEV(X, {}, undefined, false, {',
+      '    fileName: "path/to/file.js",',
+      '    lineNumber: 1,',
+      '    columnNumber: 1',
+      '  }, this);',
+      '}',
+      'function MDXContent(props = {}) {',
+      '  const {wrapper: MDXLayout} = props.components || ({});',
+      '  return MDXLayout ? _jsxDEV(MDXLayout, Object.assign({}, props, {',
+      '    children: _jsxDEV(_createMdxContent, props, undefined, false, {',
+      '      fileName: "path/to/file.js"',
+      '    }, this)',
+      '  }), undefined, false, {',
+      '    fileName: "path/to/file.js"',
+      '  }, this) : _createMdxContent(props);',
+      '}',
+      'export default MDXContent;',
+      'function _missingMdxReference(id, component, place) {',
+      '  throw new Error("Expected " + (component ? "component" : "object") + " `" + id + "` to be defined: you likely forgot to import, pass, or provide it." + (place ? "\\nIt’s referenced in your code at `" + place + "` in `path/to/file.js`" : ""));',
+      '}',
+      ''
+    ].join('\n'),
+    'should support the jsx dev runtime'
+  )
 })
 
 test('source maps', async () => {

packages/mdx/test/evaluate.js

@@ -6,6 +6,8 @@ import {renderToStaticMarkup as renderToStaticMarkup_} from '../../react/node_mo
 // @ts-expect-error: make sure a single react is used.
 import * as runtime_ from '../../react/node_modules/react/jsx-runtime.js'
 // @ts-expect-error: make sure a single react is used.
+import * as devRuntime from '../../react/node_modules/react/jsx-dev-runtime.js'
+// @ts-expect-error: make sure a single react is used.
 import React_ from '../../react/node_modules/react/index.js'
 import * as provider from '../../react/index.js'
 
@@ -30,7 +32,6 @@ test('evaluate', async () => {
 
   assert.throws(
     () => {
-      // @ts-expect-error: missing required arguments
       evaluateSync('a', {Fragment: runtime.Fragment})
     },
     /Expected `jsx` given to `evaluate`/,
@@ -39,13 +40,20 @@ test('evaluate', async () => {
 
   assert.throws(
     () => {
-      // @ts-expect-error: missing required arguments
       evaluateSync('a', {Fragment: runtime.Fragment, jsx: runtime.jsx})
     },
     /Expected `jsxs` given to `evaluate`/,
     'should throw on missing `jsxs`'
   )
 
+  assert.throws(
+    () => {
+      evaluateSync('a', {Fragment: runtime.Fragment, development: true})
+    },
+    /Expected `jsxDEV` given to `evaluate`/,
+    'should throw on missing `jsxDEV` in dev mode'
+  )
+
   assert.equal(
     renderToStaticMarkup(
       React.createElement((await evaluate('# hi!', runtime)).default)
@@ -62,6 +70,27 @@ test('evaluate', async () => {
     'should evaluate (sync)'
   )
 
+  assert.equal(
+    renderToStaticMarkup(
+      React.createElement(
+        (await evaluate('# hi dev!', {development: true, ...devRuntime}))
+          .default
+      )
+    ),
+    '<h1>hi dev!</h1>',
+    'should evaluate (sync)'
+  )
+
+  assert.equal(
+    renderToStaticMarkup(
+      React.createElement(
+        evaluateSync('# hi dev!', {development: true, ...devRuntime}).default
+      )
+    ),
+    '<h1>hi dev!</h1>',
+    'should evaluate (sync)'
+  )
+
   assert.equal(
     renderToStaticMarkup(
       React.createElement(