From 432aca5b786a13ed318a8f3a2e5252c2891b81b9 Mon Sep 17 00:00:00 2001 From: fi3ework Date: Tue, 5 Nov 2024 13:38:25 +0800 Subject: [PATCH] docs(solution): add react and node.js --- packages/create-rslib/src/index.ts | 2 +- website/docs/en/guide/solution/_meta.json | 2 +- website/docs/en/guide/solution/nodejs.mdx | 72 +++++++++++++ website/docs/en/guide/solution/react.mdx | 101 ++++++++++++++++++ website/docs/en/guide/solution/typescript.mdx | 1 - website/docs/en/guide/solution/vue.mdx | 1 - 6 files changed, 175 insertions(+), 4 deletions(-) create mode 100644 website/docs/en/guide/solution/nodejs.mdx delete mode 100644 website/docs/en/guide/solution/typescript.mdx delete mode 100644 website/docs/en/guide/solution/vue.mdx diff --git a/packages/create-rslib/src/index.ts b/packages/create-rslib/src/index.ts index 81345e4ae..b84a06558 100644 --- a/packages/create-rslib/src/index.ts +++ b/packages/create-rslib/src/index.ts @@ -27,7 +27,7 @@ async function getTemplateName({ template }: Argv) { const templateName = checkCancel( 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' }, diff --git a/website/docs/en/guide/solution/_meta.json b/website/docs/en/guide/solution/_meta.json index 67337ce6c..d81e0c779 100644 --- a/website/docs/en/guide/solution/_meta.json +++ b/website/docs/en/guide/solution/_meta.json @@ -1 +1 @@ -["react"] +["nodejs", "react"] diff --git a/website/docs/en/guide/solution/nodejs.mdx b/website/docs/en/guide/solution/nodejs.mdx new file mode 100644 index 000000000..e8da9be41 --- /dev/null +++ b/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'; + + + +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. */} diff --git a/website/docs/en/guide/solution/react.mdx b/website/docs/en/guide/solution/react.mdx index 4a55d1124..472ac3324 100644 --- a/website/docs/en/guide/solution/react.mdx +++ b/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'; + + + +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) diff --git a/website/docs/en/guide/solution/typescript.mdx b/website/docs/en/guide/solution/typescript.mdx deleted file mode 100644 index 42c977580..000000000 --- a/website/docs/en/guide/solution/typescript.mdx +++ /dev/null @@ -1 +0,0 @@ -# Typescript diff --git a/website/docs/en/guide/solution/vue.mdx b/website/docs/en/guide/solution/vue.mdx deleted file mode 100644 index 9d38c2e9d..000000000 --- a/website/docs/en/guide/solution/vue.mdx +++ /dev/null @@ -1 +0,0 @@ -# Vue