Add deprecation warning for classic runtime

Author: wooorm

packages/mdx/lib/core.js

@@ -52,6 +52,9 @@
  *   the automatic runtime compiles to `import _jsx from
  *   '$importSource/jsx-runtime'\n_jsx('p')`;
  *   the classic runtime compiles to calls such as `h('p')`.
+ *
+ *   > 👉 **Note**: support for the classic runtime is deprecated and will
+ *   > likely be removed in the next major version.
  * @property {ReadonlyArray<string> | null | undefined} [mdExtensions]
  *   List of markdown extensions, with dot (default: `['.md', '.markdown', …]`);
  *   affects integrations.
@@ -71,19 +74,28 @@
  *   `'React.createElement'`);
  *   when changing this, you should also define `pragmaFrag` and
  *   `pragmaImportSource` too.
+ *
+ *   > 👉 **Note**: support for the classic runtime is deprecated and will
+ *   > likely be removed in the next major version.
  * @property {string | null | undefined} [pragmaFrag='React.Fragment']
  *   Pragma for fragment symbol, used in the classic runtime as an identifier
  *   for unnamed calls: `<>` to `React.createElement(React.Fragment)` (default:
  *   `'React.Fragment'`);
  *   when changing this, you should also define `pragma` and
  *   `pragmaImportSource` too.
+ *
+ *   > 👉 **Note**: support for the classic runtime is deprecated and will
+ *   > likely be removed in the next major version.
  * @property {string | null | undefined} [pragmaImportSource='react']
  *   Where to import the identifier of `pragma` from, used in the classic
  *   runtime (default: `'react'`);
  *   to illustrate, when `pragma` is `'a.b'` and `pragmaImportSource` is `'c'`
  *   the following will be generated: `import a from 'c'` and things such as
  *   `a.b('h1', {})`.
  *   when changing this, you should also define `pragma` and `pragmaFrag` too.
+ *
+ *   > 👉 **Note**: support for the classic runtime is deprecated and will
+ *   > likely be removed in the next major version.
  * @property {string | null | undefined} [providerImportSource]
  *   Place to import a provider from (optional, example: `'@mdx-js/react'`);
  *   normally it’s used for runtimes that support context (React, Preact), but
@@ -148,6 +160,8 @@ const removedOptions = [
   'wrapExport'
 ]
 
+let warned = false
+
 /**
  * Create a processor to compile markdown or MDX to JavaScript.
  *
@@ -181,6 +195,19 @@ export function createProcessor(options) {
     )
   }
 
+  if (
+    !warned &&
+    (settings.jsxRuntime === 'classic' ||
+      settings.pragma ||
+      settings.pragmaFrag ||
+      settings.pragmaImportSource)
+  ) {
+    warned = true
+    console.warn(
+      "Unexpected deprecated option `jsxRuntime: 'classic'`, `pragma`, `pragmaFrag`, or `pragmaImportSource`; see <https://mdxjs.com/migrating/v3/> on how to migrate"
+    )
+  }
+
   const pipeline = unified().use(remarkParse)
 
   if (settings.format !== 'md') {

packages/mdx/readme.md

@@ -691,6 +691,9 @@ Configuration for `createProcessor` (TypeScript type).
     '$importSource/jsx-runtime'\n_jsx('p')`;
     the classic runtime compiles to calls such as `h('p')`
 
+    > 👉 **Note**: support for the classic runtime is deprecated and will
+    > likely be removed in the next major version.
+
     <details><summary>Expand example</summary>
 
     If `file` is the contents of `example.mdx` from [§ Use][use], then:
@@ -778,6 +781,9 @@ Configuration for `createProcessor` (TypeScript type).
     when changing this, you should also define `pragmaFrag` and
     `pragmaImportSource` too
 
+    > 👉 **Note**: support for the classic runtime is deprecated and will
+    > likely be removed in the next major version.
+
     <details><summary>Expand example</summary>
 
     If `file` is the contents of `example.mdx` from [§ Use][use], then:
@@ -812,13 +818,19 @@ Configuration for `createProcessor` (TypeScript type).
     for unnamed calls: `<>` to `React.createElement(React.Fragment)`;
     when changing this, you should also define `pragma` and `pragmaImportSource`
     too
-*    `pragmaImportSource` (`string`, default: `'react'`)
+
+    > 👉 **Note**: support for the classic runtime is deprecated and will
+    > likely be removed in the next major version.
+*   `pragmaImportSource` (`string`, default: `'react'`)
     — where to import the identifier of `pragma` from, used in the classic
     runtime;
     to illustrate, when `pragma` is `'a.b'` and `pragmaImportSource` is `'c'`
     the following will be generated: `import a from 'c'` and things such as
     `a.b('h1', {})`;
     when changing this, you should also define `pragma` and `pragmaFrag` too
+
+    > 👉 **Note**: support for the classic runtime is deprecated and will
+    > likely be removed in the next major version.
 *   `providerImportSource` (`string`, optional, example: `'@mdx-js/react'`)
     — place to import a provider from;
     normally it’s used for runtimes that support context (React, Preact), but

packages/mdx/test/compile.js

@@ -28,6 +28,39 @@ test('@mdx-js/mdx: compile', async function (t) {
     }, /Unexpected removed option `filepath`/)
   })
 
+  await t.test(
+    'should warn about the deprecated classic runtime',
+    async function () {
+      const warn = console.warn
+      /** @type {Array<unknown> | undefined} */
+      let messages
+
+      console.warn = capture
+
+      assert.equal(
+        renderToStaticMarkup(
+          React.createElement(
+            await run(await compile('# hi!', {jsxRuntime: 'classic'}))
+          )
+        ),
+        '<h1>hi!</h1>'
+      )
+
+      assert.deepEqual(messages, [
+        "Unexpected deprecated option `jsxRuntime: 'classic'`, `pragma`, `pragmaFrag`, or `pragmaImportSource`; see <https://mdxjs.com/migrating/v3/> on how to migrate"
+      ])
+
+      console.warn = warn
+
+      /**
+       * @param  {...unknown} args
+       */
+      function capture(...args) {
+        messages = args
+      }
+    }
+  )
+
   await t.test('should compile', async function () {
     assert.equal(
       renderToStaticMarkup(