feat(React19): add React19 adapter (Tencent#3640)

* feat(packages): add React19 adapter

* chore(package): update package config

* chore(react-render): adjust reactRender code

* chore(react-render): optimize react-render code

* chore(common-js): fix import error

* chore: optimize the use of react19 adapter

* chore: add react-19-adapter to sideEffects

* feat: add adapter file compile

* chore(react-render): adjust React19 use tdesign-react way

* chore(common): sync packages/common

---------

Co-authored-by: Heising <[email protected]>
Co-authored-by: wū yāng <[email protected]>

Author: 3 people

packages/common

@@ -0,0 +1,4 @@
+import { createRoot } from 'react-dom/client';
+import { renderAdapter } from './react-render';
+
+renderAdapter(createRoot);

packages/components/_util/react-19-adapter.ts

@@ -2,7 +2,6 @@
 // @ts-ignore
 import type * as React from 'react';
 import * as ReactDOM from 'react-dom';
-import { createRoot as createRootClient } from 'react-dom/client';
 import type { Root } from 'react-dom/client';
 
 // Let compiler not to search module usage
@@ -20,13 +19,16 @@ type CreateRoot = (container: ContainerType) => Root;
 // @ts-ignore
 const { version, render: reactRender, unmountComponentAtNode } = fullClone;
 
-let createRoot: CreateRoot;
+let legacyCreateRoot: CreateRoot;
 try {
   const mainVersion = Number((version || '').split('.')[0]);
   if (mainVersion >= 18 && mainVersion < 19) {
-    ({ createRoot } = fullClone);
-  } else if (mainVersion >= 19) {
-    createRoot = createRootClient;
+    legacyCreateRoot = fullClone.createRoot;
+  }
+  if (process.env.NODE_ENV !== 'production' && mainVersion >= 19) {
+    console.warn(
+      'TDesign warning: Please import react-19-adapter in React 19, See link: https://github.com/Tencent/tdesign-react/blob/develop/packages/tdesign-react/site/docs/getting-started.md#如何在-react-19-中使用',
+    );
   }
 } catch (e) {
   // Do nothing;
@@ -52,7 +54,7 @@ type ContainerType = (Element | DocumentFragment) & {
 
 function modernRender(node: React.ReactElement, container: ContainerType) {
   toggleWarning(true);
-  const root = container[MARK] || createRoot(container);
+  const root = container[MARK] || legacyCreateRoot(container);
   toggleWarning(false);
 
   root.render(node);
@@ -66,7 +68,7 @@ function legacyRender(node: React.ReactElement, container: ContainerType) {
 }
 
 export function render(node: React.ReactElement, container: ContainerType) {
-  if (createRoot) {
+  if (legacyCreateRoot) {
     modernRender(node, container);
     return;
   }
@@ -90,10 +92,21 @@ function legacyUnmount(container: ContainerType) {
 }
 
 export async function unmount(container: ContainerType) {
-  if (createRoot !== undefined) {
+  if (legacyCreateRoot !== undefined) {
     // Delay to unmount to avoid React 18 sync warning
     return modernUnmount(container);
   }
 
   legacyUnmount(container);
 }
+
+/**
+ * @deprecated Set React render function for compatible usage.
+ * This is internal usage only compatible with React 19.
+ * And will be removed in next major version.
+ */
+export function renderAdapter(render?: CreateRoot) {
+  if (render) {
+    legacyCreateRoot = render;
+  }
+}

packages/components/_util/react-render.ts

@@ -22,7 +22,10 @@
     "dist/*",
     "site/*",
     "es/**/style/**",
-    "esm/**/style/**"
+    "esm/**/style/**",
+    "es/_util/react-19-adapter.js",
+    "esm/_util/react-19-adapter.js",
+    "lib/_util/react-19-adapter.js"
   ],
   "publishConfig": {
     "registry": "https://registry.npmjs.org/"

packages/tdesign-react/package.json

@@ -88,7 +88,13 @@ module.exports = {
 
 ### How to use in React 19
 
-If you need to use TDesign React in React 19, please install version `[email protected]`. Since it cannot simultaneously support React 16–19, we will soon provide a  branch version for long-term compatibility with React 19.
+If you need to use it with React 19, please install at least `[email protected]`.
+
+```js
+import React from "react";
+import { createRoot } from "react-dom/client";
+import "tdesign-react/es/_util/react-19-adapter";
+```
 
 ### How to use React with Next.js
 
@@ -101,6 +107,8 @@ When using Next.js, you need to adjust how you use these components.
 
 import { Button } from 'tdesign-react/lib/';
 import 'tdesign-react/dist/tdesign.css';
+// Use it in React19 and introduce the following line
+import "tdesign-react/lib/_util/react-19-adapter";
 ```
 
 In addition, the code exported by the `lib` package is written in `es6` and is located in the `node_modules`. It will be skipped by Webpack during compilation, and you need to configure it in `next.config.js`

packages/tdesign-react/site/docs/getting-started.en-US.md

@@ -91,7 +91,13 @@ module.exports = {
 ```
 ### 如何在 React 19 中使用
 
-如果您需要在 React 19 中使用，请安装 `[email protected]` 这个版本；因为无法同时兼容React 16 -19，我们接下来会专门提供一个分支版本，长期支持在 React 19 的使用 TDesign React。
+如果您需要在 React 19 中使用，请安装最低 `[email protected]` 这个版本。
+
+```js
+import React from "react";
+import { createRoot } from "react-dom/client";
+import "tdesign-react/es/_util/react-19-adapter";
+```
 
 ### 如何在 Next.js 中使用
 
@@ -104,6 +110,8 @@ module.exports = {
 
 import { Button } from 'tdesign-react/lib/'; // 按需引入无样式组件代码
 import 'tdesign-react/dist/tdesign.css'; // 全局引入所有组件样式代码
+// 在 React19 使用，引入下面这行
+import "tdesign-react/lib/_util/react-19-adapter";
 ```
 
 此外 `lib` 包导出的是 `es6` 的代码且在 `node_modules` 中，会被 `webpack` 在编译时跳过，还需配置下 `next.config.js`。

packages/tdesign-react/site/docs/getting-started.md

@@ -14,7 +14,8 @@ import multiInput from 'rollup-plugin-multi-input';
 import nodeResolve from '@rollup/plugin-node-resolve';
 import staticImport from 'rollup-plugin-static-import';
 import ignoreImport from 'rollup-plugin-ignore-import';
-import { resolve } from 'path';
+import { resolve, join } from 'path';
+import { copy as fileCopy } from 'fs-extra';
 
 import pkg from '../packages/tdesign-react/package.json';
 
@@ -34,6 +35,7 @@ const inputList = [
   'packages/components/**/*.ts',
   'packages/components/**/*.jsx',
   'packages/components/**/*.tsx',
+  '!packages/components/_util/react-19-adapter.ts', // 单独处理 external
   '!packages/components/**/_example',
   '!packages/components/**/_example-js',
   '!packages/components/**/*.d.ts',
@@ -274,4 +276,66 @@ const resetCss = {
   plugins: [postcss({ extract: true })],
 };
 
-export default [cssConfig, libConfig, cjsConfig, esConfig, esmConfig, umdConfig, umdMinConfig, resetCss];
+// 适配 React 19 的 adapter
+const adapterInput = 'packages/components/_util/react-19-adapter.ts';
+const adapterExternal = ['react-dom', './react-render'];
+
+function postWritePlugin() {
+  return {
+    name: 'post-write-plugin',
+    async writeBundle(outputOptions) {
+      // 1. 获取写入的目录路径
+      const outputDir = outputOptions.dir;
+      const filePath = join(outputDir, 'react-19-adapter.js');
+
+      async function copyMultipleDest(src, destArray) {
+        try {
+          // 并行复制到所有目标路径
+          await Promise.all(destArray.map((dest) => fileCopy(src, dest)));
+          console.log('adapter has been coped.');
+        } catch (err) {
+          console.error('copy failed:', err);
+        }
+      }
+
+      copyMultipleDest(filePath, [
+        'packages/tdesign-react/lib/_util/react-19-adapter.js',
+        'packages/tdesign-react/esm/_util/react-19-adapter.js',
+      ]);
+    },
+  };
+}
+
+const adapterEsConfig = {
+  input: adapterInput,
+  external: adapterExternal,
+  plugins: [postWritePlugin()],
+  output: {
+    banner,
+    dir: 'packages/tdesign-react/es/_util/',
+    format: 'esm',
+  },
+};
+
+const adapterCjsConfig = {
+  input: adapterInput,
+  external: adapterExternal,
+  output: {
+    banner,
+    dir: 'packages/tdesign-react/cjs/_util/',
+    format: 'cjs',
+  },
+};
+
+export default [
+  cssConfig,
+  libConfig,
+  cjsConfig,
+  esConfig,
+  esmConfig,
+  umdConfig,
+  umdMinConfig,
+  resetCss,
+  adapterEsConfig,
+  adapterCjsConfig,
+];