Vite+React+TypeScript新项目中TypeScript无法识别JSX.IntrinsicElements中的<math-field>新元素

环境版本 #

• node v22.14.0
• typescript v5.8.3
• react v19.0.0
• @types/react v19.1.2
• @types/react-dom v19.1.2
• react-dom v19.0.0
• mathlive v0.105.0

问题背景 #

最近用Vite搭了个TS+React的新项目，想集成mathlive的<math-field>组件，结果TypeScript死活不认这个元素，报错说JSX.IntrinsicElements里找不到它的定义，折腾半天没搞定，来求个解决方案。

搞定方法 #

其实就是TypeScript默认不知道这个自定义Web组件的存在，咱们手动给React的JSX类型加个扩展就行，步骤很简单：

1. 建个类型声明文件
   在项目的src目录下新建一个custom-elements.d.ts（名字随便取，只要是.d.ts后缀就行），专门放自定义元素的类型声明。

2. 写扩展代码
   把下面这段代码粘进去，扩展JSX.IntrinsicElements接口，把<math-field>的类型加进去：

import type { MathFieldElement } from 'mathlive';

declare global {
  namespace JSX {
    interface IntrinsicElements {
      'math-field': React.DetailedHTMLProps<
        React.HTMLAttributes<MathFieldElement>,
        MathFieldElement
      >;
    }
  }
}

这样TS就知道<math-field>是合法的JSX元素了，而且还能继承原生HTML属性和mathlive给这个元素定义的专属属性，连属性提示都能正常用。

3. 检查TS配置
   打开tsconfig.json，确认include数组里包含了src/**/*，这样TS编译的时候才会加载咱们新建的声明文件，一般Vite默认的配置就有这个，不过保险起见还是看一眼。

4. 测试一下
   现在在组件里正常用<math-field>就不会报错了，比如：

function App() {
  return (
    <div className="App">
      <math-field placeholder="来写个数学公式试试~"></math-field>
    </div>
  );
}

export default App;

亲测有效，TS不会再叽叽歪歪说找不到元素了😎

备注：内容来源于stack exchange，提问作者Vladislav Maksimov