diff --git a/website/docs/en/guide/advanced/dts.mdx b/website/docs/en/guide/advanced/dts.mdx index d0fa1a9ef..9985e81d0 100644 --- a/website/docs/en/guide/advanced/dts.mdx +++ b/website/docs/en/guide/advanced/dts.mdx @@ -10,7 +10,7 @@ TypeScript Declaration Files (DTS) provide type information for JavaScript code. 2. **Code Completion**: Enhance code editor features like autocomplete and code navigation. 3. **Documentation Generation**: Generate documentation for JavaScript code, providing better developer experience. 4. **IDE Support**: Improve the developer experience in IDEs like Visual Studio Code, WebStorm, and others. -5. **Library Consumption**: Make it easier for other developers to use and understand your library. +5. **Library Consumption**: Make it easier for users to use and understand your library. ## What are Bundle DTS and Bundleless DTS @@ -50,7 +50,7 @@ If you want to generate bundleless DTS, you can: If you want to generate bundle DTS, you can: -1. Install `@microsoft/api-extractor` as a development dependency, which is the underlying tool used for bundling DTS files. +1. Install `@microsoft/api-extractor` as `devDependencies`, which is the underlying tool used for bundling DTS files. import { PackageManagerTabs } from '@theme'; diff --git a/website/docs/en/guide/advanced/module-federation.mdx b/website/docs/en/guide/advanced/module-federation.mdx index 2be11b3d6..73d85f23c 100644 --- a/website/docs/en/guide/advanced/module-federation.mdx +++ b/website/docs/en/guide/advanced/module-federation.mdx @@ -28,7 +28,7 @@ import { PackageManagerTabs } from '@theme'; -Then add the plugin to the `rslib.config.ts` file: +Then register the plugin in the `rslib.config.ts` file: ```ts title='rslib.config.ts' {8-43} import { pluginModuleFederation } from '@module-federation/rsbuild-plugin'; @@ -82,7 +82,7 @@ export default defineConfig({ }); ``` -In this way, we have completed the integration of Rslib Module as a producer. After the construction is completed, we can see that the mf directory has been added to the product, and consumers can directly consume this package +In this way, we have completed the integration of Rslib Module as a producer. After the construction is completed, we can see that the mf directory has been added to the product, and consumers can directly consume this package. In the above example we added a new `format: 'mf'` , which will help you add an additional Module Federation product, while also configuring the format of `cjs` and `esm` , which does not conflict. @@ -94,7 +94,7 @@ However, if you want this Rslib Module to consume other producers at the same ti Rslib support developing Module Federation Rslib project with a host application. -#### 1. Start MF `dev` of library +#### 1. Start `rslib mf dev` command of library Adding the `dev` command to the `package.json` file: @@ -152,7 +152,7 @@ Then start the host app with `rsbuild dev`. Rslib support developing Module Federation Rslib project with Storybook. -#### 1. Start MF `dev` of library +#### 1. Start `rslib mf dev` command of library Adding the `dev` command to the `package.json` file: @@ -310,7 +310,7 @@ This ensures that modules can be loaded as expected in multiple formats. ## FAQs If the Rslib producer is built with build, this means that the `process.env.NODE_ENV` of the producer is `production` . If the consumer is started in dev mode at this time, -Due to the shared loading policy of Module Federation being `version-first` by default, there may be problems loading into different modes of react and react-dom (e.g. react in development mode, react-dom in production mode). +due to the shared loading strategy of Module Federation being `version-first` by default, there may be problems loading into different modes of react and react-dom (e.g. react in development mode, react-dom in production mode). You can set up [shareStrategy](https://module-federation.io/configure/sharestrategy) at the consumer to solve this problem, but make sure you fully understand this configuration ```ts diff --git a/website/docs/en/guide/solution/index.mdx b/website/docs/en/guide/solution/index.mdx index 341504f57..cb0ca0190 100644 --- a/website/docs/en/guide/solution/index.mdx +++ b/website/docs/en/guide/solution/index.mdx @@ -4,8 +4,6 @@ In this chapter, we will introduce how to use Rslib to development libraries for ## Browser Target -Rslib outputs code for the browser by default, so no additional configuration is necessary to get started. - When developing a library that runs in the browser, you can package it in both [ESM](/guide/basic/output-format#esm--cjs) and [CJS](/guide/basic/output-format#esm--cjs) formats for integration with application bundlers. Configuring the package [conditional exports](https://nodejs.org/api/packages.html#conditional-exports) to ESM output allows for better tree shaking. Additionally, you can create [UMD](/guide/basic/output-format#umd) format output for direct browser use and even generate [Module Federation ](/guide/advanced/module-federation) formats for dynamic loading by other applications. Configure [Browserslist](https://rsbuild.dev/guide/advanced/browserslist) according to the target browser support to determine the downgrade syntax of the output, or adding [polyfill](/guide/advanced/output-compatibility) for API compatibility. When publishing to npm, you can choose not to [minify](/config/rsbuild/output#outputminify) your code or to minify it while providing a [sourcemap](/config/rsbuild/output#outputsourcemap) to enhance the debugging experience for users of your library. For styling, you can use [CSS](/guide/advanced/css), or [CSS pre-processors](/guide/advanced/css#preprocessors) like Sass, Less, or Stylus, or apply [PostCSS](/guide/advanced/css#postcss) for CSS post-processing. Tools like [Tailwind CSS](/guide/advanced/css#tailwind-css) can also help in building your styles. Using [CSS modules](/guide/advanced/css#css-modules) to create CSS modules is another option. @@ -19,9 +17,9 @@ Refer to the solutions in this chapter to learn how to use Rslib to develop brow ## Node.js Target -By setting set [target](/config/rsbuild/output#outputtarget) to `"node"` to development libraries for Node.js. +Rslib set [target](/config/rsbuild/output#outputtarget) to `"node"` by default to development libraries for Node.js. -You can create a [pure ESM](/guide/basic/output-format#esm--cjs) package or a [dual package](/guide/basic/output-format#esm--cjs) that supports both ESM and CJS as needed. In CJS output, `import.meta.url` will be automatically [shimmed](/config/lib/shims) for compatibility and `__dirname` and `__filename` got an optional ESM shims to ensure proper use across different module system. Node.js's built-in packages will be [externalized by default](/guide/advanced/third-party-deps), simplifying the configuration. +You can create a [pure ESM](/guide/basic/output-format#esm--cjs) package or a [dual package](/guide/basic/output-format#esm--cjs) that supports both ESM and CJS as needed. In CJS output, `import.meta.url` will be automatically [shimmed](/config/lib/shims) for compatibility and `__dirname` and `__filename` got optional ESM shims to ensure proper use across different module system. Node.js's built-in packages will be [externalized by default](/guide/advanced/third-party-deps). {/* TODO: Clarify default behavior */} {/* ### Default Behavior */} diff --git a/website/docs/en/guide/solution/nodejs.mdx b/website/docs/en/guide/solution/nodejs.mdx index b62fb3179..2c0650bb1 100644 --- a/website/docs/en/guide/solution/nodejs.mdx +++ b/website/docs/en/guide/solution/nodejs.mdx @@ -54,7 +54,7 @@ export default defineConfig({ Rslib set [target](/config/rsbuild/output#outputtarget) to `"node"` by default, which is different from the default target of Rsbuild. -Rslib adjusts many configurations for Node.js. For example, [output.externals](/config/rsbuild/output#outputtarget) 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. +When target is set to `"node"`, Rslib adjusts many configurations for Node.js. For example, [output.externals](/config/rsbuild/output#outputtarget) 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. ### Externals diff --git a/website/docs/en/guide/solution/react.mdx b/website/docs/en/guide/solution/react.mdx index 8e1ecd3f5..4c26072f3 100644 --- a/website/docs/en/guide/solution/react.mdx +++ b/website/docs/en/guide/solution/react.mdx @@ -49,7 +49,7 @@ export default defineConfig({ 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`. +By default, Rsbuild uses the new JSX transform, which is `runtime: 'automatic'`. It requires at least React `16.14.0` or higher. The `peerDependencies` should be declared as `"react": ">=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: @@ -79,7 +79,7 @@ export default defineConfig({ - **Type**: `string` - **Default**: `'react'` -When `runtime` is `'automatic'`, you can specify the import path of the JSX transform through `importSource`. +When `runtime` is set to `'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'`: diff --git a/website/docs/en/guide/start/glossary.mdx b/website/docs/en/guide/start/glossary.mdx index 8e8f67dac..269b09417 100644 --- a/website/docs/en/guide/start/glossary.mdx +++ b/website/docs/en/guide/start/glossary.mdx @@ -19,7 +19,7 @@ CJS stands for [CommonJS](https://nodejs.org/api/modules.html#modules-commonjs-m ## Bundleless -Bundleless refers to a development approach that avoids the traditional practice of bundling multiple JavaScript / TypeScript files into a single or fewer output files before serving them to the client. Instead, it aims to serve individual modules directly. +Bundleless refers to a development mode that departs from the traditional practice of bundling multiple JavaScript / TypeScript files into a single or few output files that are then served to the app. Instead, it transforms each file. ## DTS diff --git a/website/docs/en/guide/start/quick-start.mdx b/website/docs/en/guide/start/quick-start.mdx index 783607712..4bc343ce1 100644 --- a/website/docs/en/guide/start/quick-start.mdx +++ b/website/docs/en/guide/start/quick-start.mdx @@ -56,7 +56,7 @@ We're working to provide templates for more frameworks (such as Vue). ### Development Tools -`create-rslib` can help you set up some commonly used development linter tools, including [Vitest](https://vitest.dev/), [Storybook](https://storybook.js.org/). You can use the arrow keys and the space bar to make your selections. If you don't need these tools, you can simply press Enter to skip. +`create-rslib` can help you set up some commonly used development tools, including [Vitest](https://vitest.dev/), [Storybook](https://storybook.js.org/). You can use the arrow keys and the space bar to make your selections. If you don't need these tools, you can simply press Enter to skip. - Vitest is available for all templates, it will be adapted based on the template's selection. - Storybook is available for web targeted templates (React), it will be adapted based on the template's selection. @@ -70,7 +70,7 @@ We're working to provide templates for more frameworks (such as Vue). ### Optional Tools -`create-rslib` can help you set up some commonly used formatter and linter tools, including [Biome](https://biomejs.dev/), [ESLint](https://eslint.org/), and [prettier](https://prettier.io/). You can use the arrow keys and the space bar to make your selections. If you don't need these tools, you can simply press Enter to skip. +`create-rslib` can help you set up some commonly used linter and formatter tools, including [Biome](https://biomejs.dev/), [ESLint](https://eslint.org/), and [prettier](https://prettier.io/). You can use the arrow keys and the space bar to make your selections. If you don't need these tools, you can simply press Enter to skip. ```text ◆ Select additional tools (Use to select, to continue) diff --git a/website/docs/zh/guide/advanced/dts.mdx b/website/docs/zh/guide/advanced/dts.mdx index 889b94684..5bf527d7a 100644 --- a/website/docs/zh/guide/advanced/dts.mdx +++ b/website/docs/zh/guide/advanced/dts.mdx @@ -1 +1,65 @@ # 类型生成 + +本章介绍什么是 TypeScript 声明文件（DTS）以及如何在 Rslib 中生成 DTS 文件。 + +## 什么是 DTS + +TypeScript 声明文件 (DTS) 提供 JavaScript 代码的类型信息。 DTS 文件通常具有 `.d.ts` 扩展名。它们允许 TypeScript 编译器理解 JavaScript 代码的类型结构，从而实现以下功能： + +1. **类型检查**: 为 JavaScript 代码提供类型信息，帮助开发人员在编译时捕获潜在的类型错误。 +2. **代码补全**: 增强代码编辑器功能，例如自动完成和代码导航。 +3. **文档生成**: 生成 JavaScript 代码文档，提供更好的开发体验。 +4. **IDE 支持**: 改善 Visual Studio Code、WebStorm 等 IDE 中的开发者体验。 +5. **库消费**: 让其他使用者更容易使用和理解该库。 + +## 什么是 Bundle DTS 和 Bundleless DTS + +### Bundle DTS + +Bundle DTS 将多个 TypeScript 声明文件 bundle 到一个声明文件中。 + +- **优势:** + + - **简化管理**: 简化类型文件的管理和引用。 + - **容易分发**: 减少用户使用库时需要处理的文件数量。 + +- **劣势:** + - **生成复杂**: 在大型项目中，生成和维护单个 bundle 文件可能会变得复杂。 + - **调试困难**: 调试类型问题可能不像各个文件单独输出那样直观。 + +### Bundleless DTS + +Bundleless DTS 为库中的每个模块生成单独的声明文件，就像 `tsc` 一样。 + +- **优势:** + + - **模块化**: 每个模块都有自己的类型定义，使维护和调试更容易。 + - **灵活**: 适合大型项目，避免单个文件的复杂性。 + +- **劣势:** + - **多文件**: 用户在使用该库时可能需要处理多个声明文件。 + - **管理复杂**: 可能需要额外的配置才能正确引用所有文件。 + +## 如何在 Rslib 中生成 DTS + +Rslib 默认使用 [TypeScript Compiler API](https://github.com/microsoft/TypeScript/wiki/Using-the-Compiler-API) 生成 Bundleless DTS， 用 [API Extractor](https://api-extractor.com/) 生成 Bundle DTS。 + +如果你想生成 Bundleless DTS，可以： + +- 设置 `dts: true` 或者 `dts: { bundle: false }` 在 Rslib 配置文件。 + +如果你想生成 Bundle DTS，可以： + +1. 安装 `@microsoft/api-extractor` 作为 `devDependencies`, 这是用于 bundle DTS 文件的底层工具。 + +import { PackageManagerTabs } from '@theme'; + + + +2. 在 Rslib 配置文件中设置 `dts: { bundle: true }`。 + +::: tip + +你可以参考 [lib.dts](/config/lib/dts) 获取更多有关 DTS 配置的详细信息。 + +::: diff --git a/website/docs/zh/guide/advanced/module-federation.mdx b/website/docs/zh/guide/advanced/module-federation.mdx index da97a8b7b..04a8db24f 100644 --- a/website/docs/zh/guide/advanced/module-federation.mdx +++ b/website/docs/zh/guide/advanced/module-federation.mdx @@ -1 +1,330 @@ +import MF from '../start/components/MF.mdx'; +import { Tab, Tabs } from 'rspress/theme'; + # 模块联邦 + +本章介绍如何在 Rslib 中构建 [模块联邦](/guide/basic/output-format#mf) 产物。 + +## 使用场景 + +模块联邦有一些典型的使用场景，包括： + +- 允许独立应用程序（微前端架构中称为“微前端”）共享模块，而无需重新编译整个应用。 +- 不同的团队处理同一应用程序的不同部分，而无需重新编译整个应用程序。 +- 运行时中在应用间动态加载和共享代码。 + +模块联邦可以帮助你: + +- 减少代码重复 +- 提高代码可维护性 +- 减小应用程序的整体大小 +- 提高应用性能 + +## 快速开始 + +首先安装 [Module Federation Rsbuild Plugin](https://www.npmjs.com/package/@module-federation/rsbuild-plugin). + +import { PackageManagerTabs } from '@theme'; + + + +然后在 `rslib.config.ts` 中注册插件: + +```ts title='rslib.config.ts' {8-43} +import { pluginModuleFederation } from '@module-federation/rsbuild-plugin'; +import { pluginReact } from '@rsbuild/plugin-react'; +import { defineConfig } from '@rslib/core'; + +export default defineConfig({ + lib: [ + // ... 其他 format + { + format: 'mf', + output: { + distPath: { + root: './dist/mf', + }, + // production 时, 在这里使用线上 assetPrefix + assetPrefix: 'http://localhost:3001/mf', + }, + // Storybook 在 dev 下使用 + dev: { + assetPrefix: 'http://localhost:3001/mf', + }, + // Storybook 在 dev 下使用 + server: { + port: 3001, + }, + plugins: [ + pluginModuleFederation({ + name: 'rslib_provider', + exposes: { + // 这里添加 expose + }, + // 此处无法添加 "remote"，因为你可能会在一次构建中构建 "esm" 或 "cjs" 产物。 + // 如果你希望 Rslib 包使用远程模块，请参考下面。 + shared: { + react: { + singleton: true, + }, + 'react-dom': { + singleton: true, + }, + }, + }), + ], + }, + ], + output: { + target: 'web', + }, + plugins: [pluginReact()], +}); +``` + +这样，我们就完成了对 Rslib Module 生产者的集成。构建完成后，我们可以看到产物中已经添加了 mf 目录，消费者可以直接消费这个包。 + +在上面的例子中，我们添加了一个新的 `format: 'mf'` ，它将添加一个额外的模块联邦产物，同时还配置了 `cjs` 和 `esm` 的格式，它们是不冲突的。 + +但是，如果你希望此 Rslib 模块同时消费其他生产者，请不要使用构建配置 `remote` 参数，因为在其他格式下，这可能会导致错误，请参考下面使用 Module Federation 运行时的示例 + +## 开发 MF 远程模块 + +### 使用宿主应用 + +Rslib 支持宿主应用和 Rslib 模块联邦项目同时开发。 + +#### 1. 启动库的 `rslib mf dev` 命令 + +添加 `dev` 命令在 `package.json` 文件: + +```json title="package.json" +{ + "scripts": { + "dev": "rslib mf dev" + } +} +``` + +然后运行 `dev` 命令即可启动模块联邦开发模式，可被宿主应用消费， +同时具有模块热更新（HMR）功能。 + + + +#### 2. 启动宿主应用 + +设置宿主应用消费 Rslib 的模块联邦库。查看[@module-federation/rsbuild-plugin +](https://www.npmjs.com/package/@module-federation/rsbuild-plugin) 获取更多信息。 + +```ts title="rsbuild.config.ts" {8-24} +import { pluginModuleFederation } from '@module-federation/rsbuild-plugin'; +import { defineConfig } from '@rsbuild/core'; +import { pluginReact } from '@rsbuild/plugin-react'; + +export default defineConfig({ + plugins: [ + pluginReact(), + pluginModuleFederation({ + name: 'rsbuild_host', + remotes: { + rslib: 'rslib@http://localhost:3001/mf/mf-manifest.json', + }, + shared: { + react: { + singleton: true, + }, + 'react-dom': { + singleton: true, + }, + }, + // 开启这个当 Rslib 产物为 'production' 模式， 但是宿主应用是 'development' 模式。 + // 参考链接: https://lib.rsbuild.dev/guide/advanced/module-federation#faqs + shareStrategy: 'loaded-first', + }), + ], +}); +``` + +然后通过 `rsbuild dev` 启动宿主应用。 + +### 使用 Storybook + +Rslib 支持使用 Storybook 开发 Rslib 模块联邦项目。 + +#### 1. 启动库的 `rslib mf dev` 命令 + +添加 `dev` 命令在 `package.json` 文件: + +```json title="package.json" +{ + "scripts": { + "dev": "rslib mf dev" + } +} +``` + +然后运行 `dev` 命令即可启动模块联邦开发模式，可被 Storybook 消费， +同时具有模块热更新（HMR）功能。 + + + +#### 2. 创建 Storybook 配置 + +首先，在 Rslib 项目中配置 Storybook。你可以参考 [Storybook 章节](/guide/advanced/storybook)来了解如何执行此操作。在本章中，我们将使用 React 框架作为示例。 + +1. 安装以下 Storybook addon，让 Storybook 与 Rslib 模块联邦一起使用: + + - [storybook-addon-rslib](https://www.npmjs.com/package/storybook-addon-rslib): Storybook addon 会让 Storybook 加载 Rslib 配置. + - [@module-federation/storybook-addon](https://www.npmjs.com/package/@module-federation/rsbuild-plugin): Storybook 插件，为 Storybook 设置模块联邦配置。 + + + +2. 然后创建 Storybook 配置文件 `.storybook/main.ts`，指定 stories 和 addons，并设置 framework 和相应的 framework 集成。 + +```ts title=".storybook/main.ts" {18-38} +import { dirname, join } from 'node:path'; +import type { StorybookConfig } from 'storybook-react-rsbuild'; + +function getAbsolutePath(value: string): any { + return dirname(require.resolve(join(value, 'package.json'))); +} + +const config: StorybookConfig = { + stories: [ + '../stories/**/*.mdx', + '../stories/**/*.stories.@(js|jsx|mjs|ts|tsx)', + ], + framework: { + name: getAbsolutePath('storybook-react-rsbuild'), + options: {}, + }, + addons: [ + { + name: getAbsolutePath('storybook-addon-rslib'), + options: { + rslib: { + include: ['**/stories/**'], + }, + }, + }, + { + name: '@module-federation/storybook-addon/preset', + options: { + // 在添加 rslib module manifest 给 storybook dev + // 我们在上面已经设置了 dev.assetPrefix 和 server.port 到 3001 在 rslib.config.ts + remotes: { + 'rslib-module': + //还可以在这里添加 storybook 的 shared + // shared: {} + 'rslib-module@http://localhost:3001/mf/mf-manifest.json', + }, + }, + }, + ], +}; + +export default config; +``` + +#### 3. 用远程模块编写 stories + +从远程模块引入组件 + +```ts title="stories/index.stories.tsx" {2-3} +import React from 'react'; +// 在这里加载远程模块，Storybook 相当于宿主应用. +import { Counter } from 'rslib-module'; + +const Component = () => ; + +export default { + title: 'App Component', + component: Component, +}; + +export const Primary = {}; +``` + +#### 4. 在 `tsconfig.json` 中添加模块联邦类型和 stories 文件 + +```json title="tsconfig.json" +{ + "compilerOptions": { + // ... + "paths": { + "*": ["./@mf-types/*"] + } + }, + "include": ["src/**/*", ".storybook/**/*", "stories/**/*"] +} +``` + +#### 5. 启动 Storybook app + +大功告成，启动 Storybook `npx storybook dev`。 + +## 使用其他模块联合模块 + +由于 Rslib 中有多种格式，如果在构建时配置 `remote` 参数来消耗其他模块，则可能无法在所有格式下正常工作。建议通过以下方式访问 [Module Federation Runtime](https://module-federation.io/zh/guide/basic/runtime.html) + +首先安装运行时依赖 + + + +然后在运行时使用其他模块联邦模块，例如 + +```ts +import { init, loadRemote } from '@module-federation/enhanced/runtime'; +import { Suspense, createElement, lazy } from 'react'; + +init({ + name: 'rslib_provider', + remotes: [ + { + name: 'mf_remote', + entry: 'http://localhost:3002/mf-manifest.json', + }, + ], +}); + +export const Counter: React.FC = () => { + return ( +
+ loading
}> + {createElement( + lazy( + () => + loadRemote('mf_remote') as Promise<{ + default: React.FC; + }>, + ), + )} + + + ); +}; +``` + +这确保了模块可以按预期以多种格式加载。 + +## FAQs + +如果 Rslib 生产者是用 build 构建的， 这意味着生产者中的 `process.env.NODE_ENV` 是 `production` 。如果这时消费者是使用的开发模式启动，由于模块联邦默认使用共享的加载策略，可能会有 react 和 react-dom 加载模式不一致的问题 (比如 react 在 development mode, react-dom 在 production mode)。 +你可以在消费者设置 [shareStrategy](https://module-federation.io/zh/configure/sharestrategy) 来解决这个问题，这需要你确保已经完全理解了这个配置。 + +```ts +pluginModuleFederation({ + // ... + shareStrategy: 'loaded-first', +}), +``` + +## 示例 + +[Rslib 模块联邦示例](https://github.com/web-infra-dev/rslib/tree/main/examples/module-federation) + +- `mf-host`: Rsbuild App 消费者 +- `mf-react-component`: Rslib Module, 同时是消费者和生产者, 作为生产者向 `mf-host` 提供模块， 并消费 `mf-remote` +- `mf-remote`: Rsbuild App 生产者 + +[Rslib 模块联邦 Storybook 示例](https://github.com/web-infra-dev/rslib/tree/main/examples/module-federation/mf-react-component) diff --git a/website/docs/zh/guide/solution/index.mdx b/website/docs/zh/guide/solution/index.mdx index b60f2bce7..54db89149 100644 --- a/website/docs/zh/guide/solution/index.mdx +++ b/website/docs/zh/guide/solution/index.mdx @@ -1 +1,25 @@ # 解决方案 + +在本章中，将介绍如何使用 Rslib 开发浏览器和 Node.js 的库。我们还将介绍如何为不同的 UI 框架创建库。 + +## Browser Target + +开发在浏览器中运行的库时，可以将其打包为 [ESM](/guide/basic/output-format#esm--cjs) 和 [CJS](/guide/basic/output-format#esm--cjs) 格式，用于与 app 的 bundler 集成。将包 [conditional-exports](https://nodejs.org/api/packages.html#conditional-exports) 配置为 ESM 输出可以更好地进行 treeshaking。此外，你可以创建 [UMD](/guide/basic/output-format#umd) 格式输出以供浏览器直接使用，甚至可以生成 [模块联邦](/guide/advanced/module-federation) 格式以供其他应用程序动态加载。根据目标浏览器支持配置 [Browserslist](https://rsbuild.dev/zh/guide/advanced/browserslist)以确定输出的降级语法，或添加 [polyfill](/guide/advanced/output-compatibility) 用于兼容 API。 + +发布到 npm 时，你可以选择不压缩代码或[压缩代码](/config/rsbuild/output#outputminify)，同时提供[sourcemap](/config/rsbuild/output#outputsourcema) 以增强库使用者的调试体验。样式上，可以使用 [CSS](/guide/advanced/css) 或 [CSS 预处理器](/guide/advanced/css#preprocessors)，如 Sass、Less 或 Stylus 等，或使用 [PostCSS](/guide/advanced/css#postcss) 用于 CSS 后处理。 [Tailwind CSS](/guide/advanced/css#tailwind-css) 等工具也可以帮助你构建样式。或使用 [CSS Modules](/guide/advanced/css#css-modules)。 + +在资源处理方面，Rslib 处理代码中使用的[静态资源](/guide/advanced/assets)，例如 SVG 和 PNG 文件。你还可以构建[React](/guide/solution/react)、[Preact](https://github.com/web-infra-dev/rslib/tree/main/examples/preact-component-bundle-false) 或其他框架，使用 [Storybook](/guide/advanced/storybook) 进行 UI 组件开发和测试。 + +参考本章的解决方案，了解如何使用 Rslib 开发一个在浏览器中使用的库，给多种框架使用。 + +{/* TODO: Clarify default behavior */} +{/* ### Default Behavior */} + +## Node.js Target + +Rslib 默认将 [target](/config/rsbuild/output#outputtarget) 设置为 `"node"`，以方便开发 Node.js 中使用的库。 + +你可以创建一个 [pure ESM](/guide/basic/output-format#esm--cjs) 包或者 [dual package](/guide/basic/output-format#esm--cjs) 同时按需支持 ESM 和 CJS。在 CJS 输出中，由于兼容性 `import.meta.url` 会被自动 [shimmed](/config/lib/shims)，同时 `__dirname` 和 `__filename` 有可选的 ESM shims，以确保在不同的模块系统中正确使用。Node.js 中的 built-in packages 会被 [默认 externalized](/guide/advanced/third-party-deps)。 + +{/* TODO: Clarify default behavior */} +{/* ### Default Behavior */} diff --git a/website/docs/zh/guide/solution/nodejs.mdx b/website/docs/zh/guide/solution/nodejs.mdx index b0b41091a..55683570d 100644 --- a/website/docs/zh/guide/solution/nodejs.mdx +++ b/website/docs/zh/guide/solution/nodejs.mdx @@ -1 +1,71 @@ # Node.js + +在本文档中，你将学习如何使用 Rslib 构建 Node.js 库。 + +## 创建 Node.js 项目 + +使用 `create-rslib` 创建 Rslib + Node.js 项目。只需执行以下命令： + +import { PackageManagerTabs } from '@theme'; + + + +然后在提示 "Select template" 时选择 `Node.js`。 + +## 在现有 Rslib 项目中使用 + +Rslib 为 Node.js 项目提供无缝支持，允许以最少的配置轻松构建 Node.js 项目。 + +例如, 在 `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', + }, + }, + }, + ], +}); +``` + +## 用于 Node.js 的 target + +Rslib 中 [target](/config/rsbuild/output#outputtarget) 的默认值为 `"node"`，这与 Rsbuild 的 target 默认值不同。 + +当 target 为 `"node"`，Rslib 会为 Node.js 调整一些配置。例如，[output.externals](/config/rsbuild/output#outputtarget) 将 external 内置 Node.js 模块，而 [shims](/config/lib/shims) 将在 CJS 产物中为 `import.meta.url` 添加 shim。 + +### Externals + +所有 Node.js [built-in modules](https://nodejs.org/docs/latest/api/) 会默认被 external。 + +### Shims + +- `global`: 保持原样，建议使用 [globalThis](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/globalThis) 替代. +- `__filename`: 当以 ESM 格式输出时，替换 `__filename` 为 `fileURLToPath(import.meta.url)`. +- `__dirname`: 当以 ESM 格式输出时，替换 `__dirname` 为 `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/zh/guide/solution/react.mdx b/website/docs/zh/guide/solution/react.mdx index 4a55d1124..037cdb30d 100644 --- a/website/docs/zh/guide/solution/react.mdx +++ b/website/docs/zh/guide/solution/react.mdx @@ -1 +1,113 @@ # React + +在本文档中，你将学习如何使用 Rslib 构建 React 组件库。 + +## 创建 React 项目 + +你可以使用 "create-rslib" 创建 Rslib + React 项目。只需执行以下命令： + +import { PackageManagerTabs } from '@theme'; + + + +然后，当提示 "Select template" 选择 `React`。 + +## 在现有 Rslib 项目中使用 + +开发 React 组件，需要在 `rslib.config.ts` 中设置 [target](/config/rsbuild/output#outputtarget) 为 `"web"`。 这一点至关重要，因为 Rslib 默认将 `target` 设置为 `"node"`，这与 Rsbuild 的 target 默认值不同。 + +要编译 React（JSX 和 TSX），你需要注册 Rsbuild [React 插件](https://rsbuild.dev/zh/plugins/list/plugin-react)。该插件将自动添加 React 构建所需的配置。 + +例如，在 `rslib.config.ts` 中注册: + +```ts title="rslib.config.ts" {2,8-11} +import { defineConfig } from '@rslib/core'; +import { pluginReact } from '@rsbuild/plugin-react'; + +export default defineConfig({ + lib: [ + // ... + ], + output: { + target: 'web', + }, + plugins: [pluginReact(/** options here */)], +}); +``` + +## JSX Transform + +- **类型**: `'automatic' | 'classic'` +- **默认值**: `'automatic'` + +React 引入了一个 [新的 JSX transform](https://legacy.reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html) 在版本 17 中。这个新的 transform 在使用 JSX 时无需导入 `React`。 + +默认情况下，Rsbuild 使用新的 JSX 转换，即 `runtime: 'automatic'`。需要 React `16.14.0` 或更高版本。 `peerDependencies` 中应声明 `"react": ">=16.14.0"`。 + +要更改 JSX transform，可以传递 [swcReactOptions](https://rsbuild.dev/zh/plugins/list/plugin-react#swcreactoptionsruntime) 给 React plugin. 比如要使用 classic runtime 时: + +```ts title="rslib.config.ts" {13-15} +import { pluginReact } from '@rsbuild/plugin-react'; +import { defineConfig } from '@rslib/core'; + +export default defineConfig({ + lib: [ + // ... + ], + output: { + target: 'web', + }, + plugins: [ + pluginReact({ + swcReactOptions: { + runtime: 'classic', + }, + }), + ], +}); +``` + +## JSX Import Source + +- **类型**: `string` +- **默认值**: `'react'` + +当 `runtime` 的值为 `'automatic'`，可以通过 `importSource` 指定 JSX transform 的 import 路径。 + +例如，当使用 [Emotion](https://emotion.sh/)，你可以设置 `importSource` 为 `'@emotion/react'`: + +```ts title="rslib.config.ts" {13-15} +import { pluginReact } from '@rsbuild/plugin-react'; +import { defineConfig } from '@rslib/core'; + +export default defineConfig({ + lib: [ + // ... + ], + output: { + target: 'web', + }, + plugins: [ + pluginReact({ + swcReactOptions: { + importSource: '@emotion/react', + }, + }), + ], +}); +``` + +{/* TODO */} +{/* ## SVGR */} + +## 进一步了解 + +- [Rsbuild React Plugin](https://rsbuild.dev/zh/plugins/list/plugin-react#swcreactoptionsruntime) +- [SWC Compilation - jsc.transform.react](https://swc.rs/docs/configuration/compilation#jsctransformreact) diff --git a/website/docs/zh/guide/start/glossary.mdx b/website/docs/zh/guide/start/glossary.mdx index b8909dd6c..3729f90a4 100644 --- a/website/docs/zh/guide/start/glossary.mdx +++ b/website/docs/zh/guide/start/glossary.mdx @@ -1 +1,34 @@ -# 术语表 +import ESM from './components/ESM.mdx'; +import CJS from './components/CJS.mdx'; +import UMD from './components/UMD.mdx'; +import MF from './components/MF.mdx'; + +# 名词解释 + +## ESM + +ESM 代表 ECMAScript 模块， + +## CJS + +CJS 代表 [CommonJS](https://nodejs.org/api/modules.html#modules-commonjs-modules)， + +## UMD + + + +## Bundleless + +Bundleless 是指一种开发模式，它与将多个 JavaScript/TypeScript 文件 bundle 到单个或很少的输出文件中，然后再将其提供给应用的传统做法不同。相反，它为每个文件都进行 transform 转译。 + +## DTS + +DTS 表示 [TypeScript 声明文件](https://www.typescriptlang.org/docs/handbook/declaration-files/introduction.html)，为 JavaScript 代码提供类型信息。 + +## 模块联邦 + + + +## 更多 + +访问 [Rsbuild - 名词解释](https://rsbuild.dev/zh/guide/start/glossary) 和 [Rspack - 术语表](https://rspack.dev/zh/misc/glossary) 中的更多名词解释。 diff --git a/website/docs/zh/guide/start/npm-packages.mdx b/website/docs/zh/guide/start/npm-packages.mdx index 84bb11992..672672b04 100644 --- a/website/docs/zh/guide/start/npm-packages.mdx +++ b/website/docs/zh/guide/start/npm-packages.mdx @@ -1 +1,30 @@ # NPM 包 + +本文档展示了 Rslib 团队维护的所有 npm 包信息。 + +## @rslib/core + +![](https://img.shields.io/npm/v/@rslib/core?style=flat-square&colorA=564341&colorB=F8F5FF) + +Rslib 核心包，提供 CLI 命令和基于 Rsbuild 的构建功能。 + +- [npm](https://npmjs.com/package/@rslib/core) +- [Source Code](https://github.com/web-infra-dev/rslib/tree/main/packages/core) + +## rsbuild-plugin-dts + +![](https://img.shields.io/npm/v/rsbuild-plugin-dts?style=flat-square&colorA=564341&colorB=F8F5FF) + +支持为 TypeScript 生成类型声明文件的 Rsbuild 插件。 + +- [npm](https://npmjs.com/package/rsbuild-plugin-dts) +- [Source Code](https://github.com/web-infra-dev/rslib/tree/main/packages/plugin-dts) + +## create-rslib + +![](https://img.shields.io/npm/v/create-rslib?style=flat-square&colorA=564341&colorB=F8F5FF) + +用于创建新的 Rslib 项目。 + +- [npm](https://npmjs.com/package/create-rslib) +- [Source Code](https://github.com/web-infra-dev/rslib/tree/main/packages/create-rslib) diff --git a/website/docs/zh/guide/start/quick-start.mdx b/website/docs/zh/guide/start/quick-start.mdx index 1ed038f21..bcc4c4fc7 100644 --- a/website/docs/zh/guide/start/quick-start.mdx +++ b/website/docs/zh/guide/start/quick-start.mdx @@ -1 +1,133 @@ # 快速上手 + +## 环境准备 + +开始之前，需要先安装 [Node.js](https://nodejs.org/) >= 16 版本，推荐使用 Node.js LTS 版本。 + +通过以下命令检查当前的 Node.js 版本： + +```bash +node -v +``` + +如果你的环境中尚未安装 Node.js，或是版本太低，可以通过 [nvm](https://github.com/nvm-sh/nvm) 或 [fnm](https://github.com/nvm-sh/nvm) 或 [fnm](https:///github.com/Schniz/fnm) 安装。 + +下面是通过 nvm 安装的例子： + +```bash +# 安装 Node.js LTS +nvm install --lts +# 切换 Node.js LTS +nvm use --lts +``` + +## 创建一个 Rslib 项目 + +你可以使用 [`create-rslib`](https://www.npmjs.com/package/create-rslib) 创建一个 Rslib 项目。运行以下命令： + +import { PackageManagerTabs } from '@theme'; + + + +然后按照提示操作即可。 + +### 模板 + +`create-rslib` 是一个快速创建 Rslib 项目的工具。创建项目时，你可以选择以下模板： + +| Template | Description | +| ---------------------------- | ---------------------------- | +| Node.js dual ESM/CJS package | Node.js dual ESM/CJS package | +| Node.js pure ESM package | Node.js pure ESM package | +| React | React component library | + +每个模板都支持 JavaScript 和 TypeScript，以及可选的开发工具、格式化程序和 linter。 + +:::info +我们正在努力为更多框架提供模板 (比如 Vue)。 +::: + +### 开发工具 + +`create-rslib` 可以帮助你设置一些常用的开发工具，包括 [Vitest](https://vitest.dev/)、[Storybook](https://storybook.js.org/)。你可以使用方向键和空格键进行选择。如果你不需要这些工具，只需按 Enter 跳过即可。 + +- Vitest 适用于所有模板，它将根据模板的选择进行调整。 +- Storybook 可用于 Web 目标模板 (React)，它将根据模板的选择进行调整。 + +```text +◆ Select development tools (Use to select, to continue) +│ ◻ Storybook +│ ◻ Vitest +└ +``` + +### 可选工具 + +`create-rslib` 可以帮助你设置一些常用的代码检查和格式化工具，包括 [Biome](https://biomejs.dev/)、[ESLint](https://eslint.org/) 和 [prettier](https://prettier.io/)。你可以使用箭头键和空格键进行选择。如果你不需要这些工具，按 Enter 跳过即可。 + +```text +◆ Select additional tools (Use to select, to continue) +│ ◻ Add Biome for code linting and formatting +│ ◻ Add ESLint for code linting +│ ◻ Add Prettier for code formatting +└ +``` + +:::tip +Biome 提供与 ESLint 和 Prettier 类似的代码检查和格式化功能。如果你选择 Biome，通常也不需要选择 ESLint 或 Prettier。 +::: + +### 当前目录 + +如果需要在当前目录下创建项目，可以将目标文件夹设置为 `.`： + +```text +◆ Create Rslib Project +│ +◇ Project name or path +│ . +│ +◇ "." is not empty, please choose: +│ Continue and override files +``` + +### 快速生成 + +[create-rslib](https://www.npmjs.com/package/create-rslib) 提供了一些 CLI 选项。通过设置这些 CLI 选项，你可以跳过交互式的选择步骤，一键创建项目。 + +比如，一键创建 example 模版项目到 `my-project`： + +```bash +npx create-rslib --dir my-project --template example + +# 使用缩写 +npx create-rslib -d my-project -t example +``` + +`create-rslib` 的完整的 CLI 选项如下： + +```text +Usage: create-rslib [options] + +Options: + + -h, --help display help for command + -d, --dir create project in specified directory + -t, --template specify the template to use + --tools select additional tools (biome, eslint, prettier) + --override override files in target directory +``` + +## 迁移 + +如果你需要从一个现有项目迁移迁移到 Rslib，可以参考以下指南： + +- [从 tsup 迁移](/guide/migration/tsup) +- [从 Modern.js Module 迁移](/guide/migration/modernjs-module) diff --git a/website/theme/index.tsx b/website/theme/index.tsx index ae0bef88d..584d0825d 100644 --- a/website/theme/index.tsx +++ b/website/theme/index.tsx @@ -1,28 +1,10 @@ -import { Announcement } from '@rstack-dev/doc-ui/announcement'; import { NavIcon } from '@rstack-dev/doc-ui/nav-icon'; -import { NoSSR, useLang, usePageData } from 'rspress/runtime'; import Theme from 'rspress/theme'; import { HomeLayout } from './pages'; import './index.scss'; const Layout = () => { - const { page } = usePageData(); - const lang = useLang(); - return ( - } - beforeNav={ - - - - } - /> - ); + return } />; }; export default {