经过两年半的等待开发,MDX v2 终于发布了。MDX v2 在性能和语法等领域对 MDX v1 的功能进行了一些急需的改进,并添加了对 JavaScript 表达式和更多 JSX 运行时的支持等功能。
在本文中,我们将探讨 MDX v2 发行说明中突出显示的一些惊人改进,包括:
- 改进的 MDX 语法格式
- 支持 JavaScript 表达式
- 增加和扩展对 JSX 运行时的支持
- 支持 ES 模块
- 改进的文档
- 架构改进
- 打字稿支持
- 如何将您的 React、Preact 和 Vue 应用程序迁移到 MDX v2
- 可能的 MDX v2 重大更改
改进的 MDX 语法格式
与第一个版本相比,新改进的 MDX 语法使得在 JSX 中使用 MDX 更加容易。根据 MDX 团队的发布帖子,
我们花了很多时间思考和尝试不同的方法来改进格式。最初,该格式非常接近 Markdown 和 Markdown 中的 HTML 的工作方式。我们发现旧的行为往往会产生意想不到的结果。在版本 2 中,我们将格式转换为更接近 JS(X) 的工作方式。
在旧格式中,MDX 语法被转换为其相对的 Markdown 格式,如下所示:
<div>*italicize*</div>
转换成<div>*italicize*</div>
<div># header one</div>
转换成<div># header one</div>
但这引起了广泛的解析问题。使用新语法,MDX 代码将直接转换为等效的 JSX 格式:
<div>*italicize*</div>
变成<div><em>italicize</em></div>
<div># header one</div>
变成<div><h1>header one</h1></div>
此更新承诺解决 MDX v1 语法中遇到的解析问题。
支持 JavaScript 表达式
MDX v2 支持向 MDX 代码添加表达式,例如 JavaScript 表达式。表达式可以添加到 MDX 文档中大括号内的任何位置,并且不需要限制在文档的某些区域。
现在,您可以直接在 MDX 代码中执行算术运算等令人惊奇的事情。例如,这段代码:
# 快速数学 -> { (2+2) * Math.PI}
产生这个输出:
快速数学-> 12.566370614359172
表达式的花括号也可以为空或包含注释。
{ / * 这是一个可爱的评论!* / }
增加和扩展对 JSX 运行时的支持
MDX v2 增加了对更多 JavaScript 运行时和捆绑器的支持。v1 版本的 MDX 主要与 Babel、webpack 和 React 一起工作,并且不能轻松地与其他工具一起使用。
这在 v2 版本中已更改。Babel、webpack 和 React 现在是可选的,MDX 现在可以用于:
- Vue (@mdx-js/vue)
- React (@mdx-js/react)
- Preact (@mdx-js/preact)
- Svelte (svelte-jsx)
- esbuild (@mdx-js/esbuild)
- Rollup (@mdx-js/rollup)
- webpack (@mdx-js/loader)
- Directly into Node.js documents (@mdx-js/node-loader) of versions ≥ 12.20, 14.14, or 16.0
支持 ES 模块
MDX v2 已完全切换为仅支持 ECMAScript 模块 (ESM)。虽然 MDX v1 提供对 ESM 的支持,但 v2 仅适用于支持 ESM 的工具。因此,像下面这样的导入将不适用于 MDX v2。
const data = require('./data')
import { foo } from 'foo/lib/main'
您必须改为将其更改为 ESM JavaScript。
import data from './data.js'
import { foo } from 'foo/lib/main.js'
改进的文档
整个 MDX 文档已从上到下重新编写,以便为尝试修改 MDX v2 的人们提供更好的体验。所有不一致和重复的内容也已从文档网站中删除。
文档网站也使用 MDX 进行了重建,并提供了更优化的体验和性能。根据 MDX 团队的说法,与之前的版本相比,新的文档网站在所有性能和可访问性测试中的得分都很高。
架构改进
整个 MDX 架构已被重写,以提高新版本中的性能和功能。新架构具有:
- 更快的错误标记
- 更好的 MDX 语法
- 支持更多运行时和捆绑器
但最令人兴奋的特性是改进的抽象语法树(AST)。新的 AST 更详细地描述了 MDX v2 语法,这将通过允许插件以新的方式增强 MDX 来改善围绕 MDX 的生态系统,并帮助 MDX 解决以前可能导致崩溃的边缘情况。
MDX 团队声称,改进后的架构将编译时间比之前的版本缩短了 25%,生成代码的速度提高了 100%,并且包大小比使用 MDX v1 编写的那些小 250%。
您可以在发行说明中了解有关改进架构的更多信息。
打字稿支持
改进后的 MDX 架构还支持 TypeScript。根据 MDX 团队的说法,
现在,所有@mdx-js/* 包都通过 JSDoc 注释使用 TypeScript 完全输入。这意味着我们的 API 以 TypeScript 类型公开,而且我们的项目在内部是类型安全的。
要将 TypeScript 支持添加到您的 MDX 文档,请安装@types/mdx。
npm install @types / mdx
TypeScript 应该会在安装后自动获取 MDX 文档。
将您的 React、Vue 和 Preact 应用程序迁移到 MDX v2
在将您的应用程序迁移到 MDX v2 之前,请确保您使用的是最新版本的 React、Preact 或 Vue 3。另外,请注意,不支持 ESM 的工具将无法在 MDX v2 中运行,您可以在此处了解有关 MDX v2 ESM 支持的更多信息.
您可以使用以下命令更新您的 React 版本。
npm install --保存react@latest
然后,使用以下命令安装(@mdx-js/react) 。
npm install @mdx - js /反应
要将 MDX v2 添加到 Vue CLI,首先,使用以下命令更新您的 Vue 应用程序。
npm更新-g @vue / cli
使用以下命令安装(@mdx-js/vue) 。
npm install @mdx - js / vue
要将 MDX v2 添加到 Preact 应用程序,首先,安装最新版本的 Preact。
npm install preact
然后使用以下命令安装(@mdx-js/preact) 。
npm install @mdx - js / preact
有关如何从 MDX v1 迁移到 MDX v2 的更多说明,请访问 MDX 迁移指南。
可能的 MDX v2 重大更改
由于新语法,升级到新版本后,您可能会从 MDX 文件中收到错误。仔细研究错误消息以了解您遇到的错误以及如何修复错误。以下是一些常见的:
Could not parse import/exports with acorn: $error
— 当您使用无效import
或export
语句时会发生这种情况Unexpected end of file in expression, expected a corresponding closing brace for `{`: $error
— 当您有一个左大括号而没有右大括号时会发生这种情况Could not parse expression with acorn: $error
— 当花括号内的表达式无效时会发生这种情况Could not parse expression with acorn: Unexpected content after expression
— 当花括号中的表达式过多时会发生这种情况
有关更多错误以及如何解决它们,请参阅 MDX v2 故障排除指南。
ESM 支持的迁移问题
如果您在将 MDX v2 与特定工具集成时遇到问题,这很可能是由于 MDX v2 ESM 支持所致。与 MDX v1 不同,MDX v2 仅适用于支持 ESM 的工具。
结论
在本文中,我们谈到了新发布的 MDX v2。我们讨论了架构和语法的改进、可能的重大更改,以及如何迁移到 React、Vue 和 Preact 应用程序的新版本。
新发布的 MDX v2 为 MDX 语言带来了一些急需的改进。由于减少了解析问题,改进的语法应该使 MDX 更易于使用。增加对更多 JSX 运行时的支持也应该会增加更多前端框架对它的采用。
更多的改进还在继续——现在,我们知道对 JavaScript 变量声明的支持预计将在 v2.1中发布,而MDX 插件预计将在 v2.2 中发布。