export const info = { author: [ {github: 'wooorm', name: 'Titus Wormer', twitter: 'wooorm'} ], modified: new Date('2023-10-24'), published: new Date('2023-10-24') } export const navExclude = true
A couple small changes this time around. For most folks, updating Node.js and plugins is all that’s needed!
- Update Node.js
- Update plugins
- Pass
baseUrl
toevaluate
,run
- Use the automatic JSX runtime
- Replace
MDXContext
,withMDXComponents
withuseMDXComponents
- Replace
@mdx-js/register
with@mdx-js/node-loader
If you’re still on old Node, it’s time to update. Use at least Node 16.
If you use rehype and remark plugins: update.
Most of them remain working between versions.
Particularly if you use TypeScript, there was a breaking internal change in the
types, which is now supported here.
There were also some small internal changes in how the parser works, which
affect remark-gfm
and remark-math
.
If you use evaluate
or run
(or outputFormat: 'function-body'
), you should
pass the baseUrl
option.
Likely set to import.meta.url
.
If MDX content uses export
statements, import
expressions/statements,
or import.meta.url
, we compile to code that works, but it needs to know
where the code runs: you need to pass where you are.
You will get a runtime error if these features are used in MDX without
baseUrl
.
If you passed the useDynamicImport
option before, remove it, the behavior
is now the default.
If you use react/jsx-runtime
, you might get a TypeScript error (such as
Property 'Fragment' is missing in type
), because it is typed incorrectly.
To remediate this, do:
import {type Fragment, type Jsx, run} from '@mdx-js/mdx'
import * as runtime_ from 'react/jsx-runtime'
// @ts-expect-error: the automatic react runtime is untyped.
const runtime: {Fragment: Fragment; jsx: Jsx; jsxs: Jsx} = runtime_
const result = await run('# hi', {...runtime, baseUrl: import.meta.url})
If you use the classic runtime, switch to the automatic runtime. Classic is still supported but you will now see a warning if you use the classic JSX runtime.
The classic runtime can still be nice in other places, but it causes potential
problems in MDX.
If you specify jsxRuntime: 'classic'
(and pragma
, pragmaFrag
,
pragmaImportSource
), consider switching to automatic
.
All major frameworks support the automatic runtime.
Support for the classic runtime will likely be removed next major.
If you use the deprecated symbols MDXContext
and withMDXComponents
, use
useMDXComponents
instead.
Reminder: you probably don’t need the context based @mdx-js/react
or
@mdx-js/preact
packages.
If you use the deprecated package @mdx-js/register
, use @mdx-js/node-loader
instead.