API 参考

编译库

本指南旨在帮助库作者了解如何使用 React Compiler 将优化的库代码交付给用户。

¥This guide helps library authors understand how to use React Compiler to ship optimized library code to their users.

为什么要发布编译后的代码？

¥Why Ship Compiled Code?

作为库作者，你可以在发布到 npm 之前编译库代码。这有几个好处：

¥As a library author, you can compile your library code before publishing to npm. This provides several benefits:

  • 为所有用户带来性能提升 - 即使你的库用户尚未使用 React Compiler，他们也能获得优化的代码。

    ¥Performance improvements for all users - Your library users get optimized code even if they aren’t using React Compiler yet

  • 用户无需配置 - 优化功能开箱即用

    ¥No configuration required by users - The optimizations work out of the box

  • 一致的行为 - 所有用户无论采用何种构建设置，都能获得相同的优化版本

    ¥Consistent behavior - All users get the same optimized version regardless of their build setup

设置编译

¥Setting Up Compilation

将 React Compiler 添加到你的库的构建过程中：

¥Add React Compiler to your library’s build process:

Terminal
npm install -D babel-plugin-react-compiler@rc

配置你的构建工具以编译你的库。例如，使用 Babel：

¥Configure your build tool to compile your library. For example, with Babel:

// babel.config.js
module.exports = {
  plugins: [
    'babel-plugin-react-compiler',
  ],
  // ... other config
};

向后兼容性

¥Backwards Compatibility

如果你的库支持 React 19 以下的版本，则需要进行额外配置：

¥If your library supports React versions below 19, you’ll need additional configuration:

1. 安装运行时软件包

¥ Install the runtime package

我们建议安装 react-compiler-runtime 作为直接依赖：

¥We recommend installing react-compiler-runtime as a direct dependency:

Terminal
npm install react-compiler-runtime@rc
{
  "dependencies": {
    "react-compiler-runtime": "^19.1.0-rc.2"
  },
  "peerDependencies": {
    "react": "^17.0.0 || ^18.0.0 || ^19.0.0"
  }
}

2. 配置目标版本

¥ Configure the target version

设置你的库支持的最低 React 版本：

¥Set the minimum React version your library supports:

{
  target: '17', // Minimum supported React version
}

测试策略

¥Testing Strategy

在编译和不编译的情况下测试你的库，以确保兼容性。针对编译后的代码运行现有的测试套件，并创建一个单独的测试配置来绕过编译器。这有助于捕获编译过程中可能出现的任何问题，并确保你的库在所有情况下都能正常工作。

¥Test your library both with and without compilation to ensure compatibility. Run your existing test suite against the compiled code, and also create a separate test configuration that bypasses the compiler. This helps catch any issues that might arise from the compilation process and ensures your library works correctly in all scenarios.

故障排除

¥Troubleshooting

库不支持旧版 React 版本

¥Library doesn’t work with older React versions

如果你编译的库在 React 17 或 18 中抛出错误：

¥If your compiled library throws errors in React 17 or 18:

  1. 验证是否已将 react-compiler-runtime 安装为依赖

    ¥Verify you’ve installed react-compiler-runtime as a dependency

  2. 检查你的 target 配置是否与你支持的最低 React 版本匹配

    ¥Check that your target configuration matches your minimum supported React version

  3. 确保运行时包包含在你发布的 bundle 中

    ¥Ensure the runtime package is included in your published bundle

与其他 Babel 插件编译冲突

¥Compilation conflicts with other Babel plugins

某些 Babel 插件可能与 React 编译器冲突：

¥Some Babel plugins may conflict with React Compiler:

  1. 将 babel-plugin-react-compiler 放置在插件列表的早期位置

    ¥Place babel-plugin-react-compiler early in your plugin list

  2. 禁用其他插件中冲突的优化

    ¥Disable conflicting optimizations in other plugins

  3. 彻底测试你的构建输出

    ¥Test your build output thoroughly

未找到运行时模块

¥Runtime module not found

如果用户看到 “找不到模块 ‘react-compiler-runtime’”：

¥If users see “Cannot find module ‘react-compiler-runtime’“:

  1. 确保运行时在 dependencies 中列出，而不是 devDependencies

    ¥Ensure the runtime is listed in dependencies, not devDependencies

  2. 检查你的打包器是否在输出中包含运行时

    ¥Check that your bundler includes the runtime in the output

  3. 验证软件包是否已随库一起发布到 npm

    ¥Verify the package is published to npm with your library

下一步

¥Next Steps

上一章"use no memo"