docs(solution): add react and node.js (#374)

Author: fi3ework

packages/create-rslib/src/index.ts

@@ -27,7 +27,7 @@ async function getTemplateName({ template }: Argv) {
 
   const templateName = checkCancel<TemplateName>(
     await select({
-      message: 'Select templates',
+      message: 'Select template',
       options: [
         { value: 'node-dual', label: 'Node.js dual ESM/CJS package' },
         { value: 'node-esm', label: 'Node.js pure ESM package' },

website/docs/en/guide/solution/_meta.json

@@ -1 +1 @@
-["react"]
+["nodejs", "react"]

website/docs/en/guide/solution/nodejs.mdx

@@ -0,0 +1,72 @@
+# Node.js
+
+In this document, you will learn how to build a Node.js library using Rslib.
+
+## Create Node.js Project
+
+You can use `create-rslib` to create a project with Rslib + Node.js. Just execute the following command:
+
+import { PackageManagerTabs } from '@theme';
+
+<PackageManagerTabs
+  command={{
+    npm: 'npm create rslib@latest',
+    yarn: 'yarn create rslib',
+    pnpm: 'pnpm create rslib@latest',
+    bun: 'bun create rslib@latest',
+  }}
+/>
+
+Then select `Node.js` when prompted to "Select template".
+
+## Use Rslib in an existing project
+
+To development an Node.js library, you need to set [target](/config/rsbuild/output#target) to `"node"` in `rslib.config.ts`. This is crucial because when the `target` is set to `"node"`, Rslib automatically adjusts many configurations for Node.js. For example, [output.externals](/config/rsbuild/output#target) will exclude built-in Node.js modules, and [shims](/config/lib/shims) will add a shim for `import.meta.url` in CJS output by default.
+
+For example, in `rsbuild.config.ts`:
+
+```ts title="rslib.config.ts"
+import { defineConfig } from '@rslib/core';
+
+export default defineConfig({
+  lib: [
+    {
+      format: 'esm',
+      output: {
+        distPath: {
+          root: './dist/esm',
+        },
+      },
+    },
+    {
+      format: 'cjs',
+      output: {
+        distPath: {
+          root: './dist/cjs',
+        },
+      },
+    },
+  ],
+  output: {
+    target: 'node',
+  },
+});
+```
+
+## Target for Node.js
+
+When [target](/config/rsbuild/output#target) is set to `"node"`, Rslib will automatically adjust the following configurations:
+
+### Externals
+
+All Node.js [built-in modules](https://nodejs.org/docs/latest/api/) are externalized by default.
+
+### Shims
+
+- `global`: leave it as it is, while it's recommended to use [globalThis](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/globalThis) instead.
+- `__filename`: When outputting in ESM format, replace `__filename` with the result of `fileURLToPath(import.meta.url)`.
+- `__dirname`: When outputting in ESM format, replace `__dirname` with the result of `dirname(fileURLToPath(import.meta.url))`.
+
+{/* TODO: Rspack doesn't support createRequire now */}
+{/* ### createRequire */}
+{/* Requiring module with [createRequire](https://nodejs.org/api/module.html#modulecreaterequirefilename) will also works in ESM format. */}

website/docs/en/guide/solution/react.mdx

@@ -1 +1,102 @@
 # React
+
+In this document, you will learn how to build a React component library with Rslib.
+
+## Create React Project
+
+You can use `create-rslib` to create a project with Rslib + React. Just execute the following command:
+
+import { PackageManagerTabs } from '@theme';
+
+<PackageManagerTabs
+  command={{
+    npm: 'npm create rslib@latest',
+    yarn: 'yarn create rslib',
+    pnpm: 'pnpm create rslib@latest',
+    bun: 'bun create rslib@latest',
+  }}
+/>
+
+Then select `React` when prompted to "Select template".
+
+## Use Rslib in an Existing Project
+
+To compile React (JSX and TSX), you need to register the Rsbuild [React Plugin](https://rsbuild.dev/plugins/list/plugin-react). The plugin will automatically add the necessary configuration for React builds.
+
+For example, register in `rslib.config.ts`:
+
+```ts title="rslib.config.ts" {2,8}
+import { defineConfig } from '@rslib/core';
+import { pluginReact } from '@rsbuild/plugin-react';
+
+export default defineConfig({
+  lib: [
+    // ...
+  ],
+  plugins: [pluginReact(/** options here */)],
+});
+```
+
+## JSX Transform
+
+- **Type**: `'automatic' | 'classic'`
+- **Default**: `'automatic'`
+
+React introduced a [new JSX transform](https://legacy.reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html) in version 17. This new transform removes the need to import `React` when using JSX.
+
+By default, Rsbuild uses the new JSX transform, which is `runtime: 'automatic'`. It requires at least React `16.14.0` or higher. The peer dependency for React should be declared as above `16.14.0`.
+
+To change the JSX transform, you can pass the [swcReactOptions](https://rsbuild.dev/plugins/list/plugin-react#swcreactoptionsruntime) option to the React plugin. For example, to use the classic runtime:
+
+```ts title="rslib.config.ts" {10-12}
+import { pluginReact } from '@rsbuild/plugin-react';
+import { defineConfig } from '@rslib/core';
+
+export default defineConfig({
+  lib: [
+    // ...
+  ],
+  plugins: [
+    pluginReact({
+      swcReactOptions: {
+        runtime: 'classic',
+      },
+    }),
+  ],
+});
+```
+
+## JSX Import Source
+
+- **Type**: `string`
+- **Default**: `'react'`
+
+When `runtime` is `'automatic'`, you can specify the import path of the JSX transform through `importSource`.
+
+For example, when using [Emotion](https://emotion.sh/), you can set `importSource` to `'@emotion/react'`:
+
+```ts title="rslib.config.ts" {10-12}
+import { pluginReact } from '@rsbuild/plugin-react';
+import { defineConfig } from '@rslib/core';
+
+export default defineConfig({
+  lib: [
+    // ...
+  ],
+  plugins: [
+    pluginReact({
+      swcReactOptions: {
+        importSource: '@emotion/react',
+      },
+    }),
+  ],
+});
+```
+
+{/* TODO */}
+{/* ## SVGR */}
+
+## Further Reading
+
+- [Rsbuild React Plugin](https://rsbuild.dev/plugins/list/plugin-react#swcreactoptionsruntime)
+- [SWC Compilation - jsc.transform.react](https://swc.rs/docs/configuration/compilation#jsctransformreact)