feat(react): introduce @lynx-js/react/debug

.changeset/cruel-rocks-open.md

@@ -0,0 +1,5 @@
+---
+"create-rspeedy": patch
+---
+
+Add `import '@lynx-js/react/debug'` for all templates.

.changeset/smooth-bars-listen.md

@@ -0,0 +1,18 @@
+---
+"@lynx-js/react": patch
+---
+
+Introduce `@lynx-js/react/debug` which would include debugging warnings and error messages for common mistakes found.
+
+Add the import to `@lynx-js/react/debug` at the first line of the entry:
+
+```js
+import '@lynx-js/react/debug';
+import { root } from '@lynx-js/react';
+
+import { App } from './App.jsx';
+
+root.render(
+  <App />,
+);
+```

.changeset/spicy-seas-shout.md

@@ -0,0 +1,5 @@
+---
+"@lynx-js/react-alias-rsbuild-plugin": patch
+---
+
+Support `@lynx-js/react/debug`.

examples/react/src/index.tsx

@@ -1,3 +1,4 @@
+import '@lynx-js/react/debug';
 import { root } from '@lynx-js/react';
 
 import { App } from './App.jsx';

packages/react/package.json

@@ -14,6 +14,11 @@
       "lazy": "./runtime/lazy/react.js",
       "default": "./runtime/lib/index.js"
     },
+    "./debug": {
+      "types": "./runtime/debug/index.d.ts",
+      "lazy": "./runtime/debug/index.js",
+      "default": "./runtime/debug/index.js"
+    },
     "./experimental/lazy/import": {
       "types": "./runtime/lazy/import.d.ts",
       "default": "./runtime/lazy/import.js"

packages/react/runtime/.npmignore

@@ -1,4 +1,6 @@
 *
+!debug/*
+!debug/**
 !jsx-dev-runtime/*
 !jsx-runtime/*
 !lazy/*
@@ -7,5 +9,3 @@
 !lepus/*
 !lib/**
 !lib/*
-!src/**
-!src/*

packages/react/runtime/debug/index.cjs

@@ -0,0 +1,8 @@
+// Copyright 2025 The Lynx Authors. All rights reserved.
+// Licensed under the Apache License Version 2.0 that can be found in the
+// LICENSE file in the root directory of this source tree.
+
+if (process.env.NODE_ENV === 'development') {
+  // eslint-disable-next-line n/no-extraneous-require
+  require('preact/debug');
+}

packages/react/runtime/debug/index.d.ts

@@ -0,0 +1,4 @@
+// Copyright 2025 The Lynx Authors. All rights reserved.
+// Licensed under the Apache License Version 2.0 that can be found in the
+// LICENSE file in the root directory of this source tree.
+export {};

packages/react/runtime/debug/index.js

@@ -0,0 +1,5 @@
+// Copyright 2025 The Lynx Authors. All rights reserved.
+// Licensed under the Apache License Version 2.0 that can be found in the
+// LICENSE file in the root directory of this source tree.
+
+import './index.cjs';

packages/react/runtime/tsconfig.json

@@ -12,6 +12,7 @@
     "path": "../worklet-runtime/tsconfig.json",
   }],
   "include": [
+    "debug",
     "jsx-dev-runtime",
     "jsx-runtime",
     "lepus",

packages/react/runtime/vitest.config.ts

@@ -74,6 +74,7 @@ export default defineConfig({
     name: 'react/runtime',
     coverage: {
       exclude: [
+        'debug',
         'jsx-runtime',
         'jsx-dev-runtime',
         'lepus/jsx-dev-runtime',

packages/rspeedy/create-rspeedy/template-react-js/src/index.jsx

@@ -1,3 +1,4 @@
+import '@lynx-js/react/debug'
 import { root } from '@lynx-js/react'
 
 import { App } from './App.jsx'

packages/rspeedy/create-rspeedy/template-react-ts/src/index.tsx

@@ -1,3 +1,4 @@
+import '@lynx-js/react/debug'
 import { root } from '@lynx-js/react'
 
 import { App } from './App.js'

packages/rspeedy/create-rspeedy/template-react-vitest-rltl-js/src/index.jsx

@@ -1,3 +1,4 @@
+import '@lynx-js/react/debug'
 import { root } from '@lynx-js/react'
 
 import { App } from './App.jsx'

packages/rspeedy/create-rspeedy/template-react-vitest-rltl-ts/src/index.tsx

@@ -1,3 +1,4 @@
+import '@lynx-js/react/debug'
 import { root } from '@lynx-js/react'
 
 import { App } from './App.jsx'

packages/rspeedy/plugin-react-alias/src/index.ts

@@ -53,7 +53,7 @@ export function pluginReactAlias(options: Options): RsbuildPlugin {
         })
       })
 
-      api.modifyBundlerChain(async chain => {
+      api.modifyBundlerChain(async (chain, { isProd }) => {
         const [
           jsxRuntimeBackground,
           jsxRuntimeMainThread,
@@ -117,6 +117,8 @@ export function pluginReactAlias(options: Options): RsbuildPlugin {
         // react-transform may add imports of the following entries
         // We need to add aliases for that
         const transformedEntries = [
+          // TODO: add `debug` after bump peerDependencies['@lynx-js/react'] to 0.111.1
+          // 'debug',
           'experimental/lazy/import',
           'internal',
           'legacy-react-runtime',
@@ -137,6 +139,10 @@ export function pluginReactAlias(options: Options): RsbuildPlugin {
             ),
         )
 
+        if (isProd) {
+          chain.resolve.alias.set('@lynx-js/react/debug$', false)
+        }
+
         chain
           .resolve
           .alias

packages/rspeedy/plugin-react-alias/test/index.test.ts

@@ -66,6 +66,10 @@ describe('React - alias', () => {
       ),
     )
 
+    expect(config.resolve.alias).not.toHaveProperty(
+      '@lynx-js/react/debug$',
+    )
+
     expect(config.resolve.alias).toHaveProperty(
       'preact$',
       expect.stringContaining(
@@ -194,6 +198,11 @@ describe('React - alias', () => {
         '/packages/react/runtime/lib/internal.js'.replaceAll('/', path.sep),
       ),
     )
+
+    expect(config.resolve.alias).toHaveProperty(
+      '@lynx-js/react/debug$',
+      false,
+    )
   })
 
   test('alias once', async () => {