docs: complete multiple pages under /guide

fi3ework · fi3ework · commit 6a9338136172 · 2024-11-01T17:38:39.000+08:00
diff --git a/packages/core/src/types/config/index.ts b/packages/core/src/types/config/index.ts
@@ -41,6 +41,7 @@ export type AutoExternal =
   | boolean
   | {
       dependencies?: boolean;
+      optionalDependencies?: boolean;
       devDependencies?: boolean;
       peerDependencies?: boolean;
     };
diff --git a/packages/create-rslib/src/index.ts b/packages/create-rslib/src/index.ts
@@ -37,6 +37,16 @@ async function getTemplateName({ template }: Argv) {
     }),
   );
 
+  const language = checkCancel<string>(
+    await select({
+      message: 'Select language',
+      options: [
+        { value: 'ts', label: 'TypeScript' },
+        { value: 'js', label: 'JavaScript' },
+      ],
+    }),
+  );
+
   const supportStorybook = templateName === 'react';
 
   type ExcludesFalse = <T>(x: T | false) => x is T;
@@ -56,16 +66,6 @@ async function getTemplateName({ template }: Argv) {
     }),
   );
 
-  const language = checkCancel<string>(
-    await select({
-      message: 'Select language',
-      options: [
-        { value: 'ts', label: 'TypeScript' },
-        { value: 'js', label: 'JavaScript' },
-      ],
-    }),
-  );
-
   return composeTemplateName({
     template: templateName,
     lang: language as Lang,
diff --git a/website/docs/en/guide/advanced/_meta.json b/website/docs/en/guide/advanced/_meta.json
@@ -1,6 +1,5 @@
 [
   "package-json",
-  "templates",
   "third-party-deps",
   "polyfill",
   "css",
diff --git a/website/docs/en/guide/advanced/templates.mdx b/website/docs/en/guide/advanced/templates.mdx
diff --git a/website/docs/en/guide/advanced/third-party-deps.mdx b/website/docs/en/guide/advanced/third-party-deps.mdx
@@ -1 +1,81 @@
 # Handle Third-party Dependencies
+
+Generally, third-party dependencies required by a project can be installed via the `install` command in the package manager. After the third-party dependencies are successfully installed, they will generally appear under `dependencies` and `devDependencies` in the project `package.json`.
+
+```json title="package.json"
+{
+  "dependencies": {},
+  "devDependencies": {}
+}
+```
+
+Dependencies under `"dependencies"` are generally related to project code and builds, and if these third-party dependencies are declared under `"devDependencies"`, then there will be missing dependencies in production runtime.
+
+In addition to `"dependencies"`, [`"peerDependencies"`](/en/guide/basic/before-getting-started#peerdependencies) can also declare dependencies that are needed in the production environment, but it puts more emphasis on the existence of these dependencies declared by `"peerDependencies"` in the project's runtime environment, similar to the plugin mechanism.
+
+## Default handling of third-party dependencies
+
+By default, **third-party dependencies under `"dependencies"`, `"optionalDependencies"` and `"peerDependencies"` are not bundled by Rslib**.
+
+This is because when the npm package is installed, its `"dependencies"` will also be installed. By not packaging `"dependencies"`, you can reduce the size of the package product.
+
+If you need to package some dependencies, it is recommended to move them from `"dependencies"` to `"devDependencies"`, which is equivalent to **prebundle** the dependencies and reduces the size of the dependency installation.
+
+### Example
+
+If the project has a dependency on `react`.
+
+```json title="package.json"
+{
+  "dependencies": {
+    "react": "^18"
+  },
+  // or
+  "peerDependencies": {
+    "react": "^18"
+  }
+}
+```
+
+When a `react` dependency is used in the source code:
+
+```tsx title="src/index.ts"
+import React from 'react';
+console.info(React);
+```
+
+The `react` code will not be bundled into the output:
+
+```js title="dist/index.js"
+import * as __WEBPACK_EXTERNAL_MODULE_react__ from 'react';
+console.info(__WEBPACK_EXTERNAL_MODULE_react__['default']);
+```
+
+If you want to modify the default processing, you can use the following API.
+
+- [`lib.autoExternal`](/config/lib/auto-external)
+
+## Exclude specified third-party dependencies
+
+We previously introduced the use of [`lib.autoExternal`](/config/lib/auto-external). This configuration lets you manage third-party dependencies more precisely.
+
+For example, when we need to leave only certain dependencies unbundled, we can configure it as follows.
+
+:::tip
+In this case, some dependencies may not be suitable for bundling. If so, you can handle it as follows.
+:::
+
+```ts
+export default defineConfig({
+  lib: [
+    {
+      // ...
+      autoExternal: true,
+      output: {
+        externals: ['pkg-1', /pkg-2/],
+      },
+      // ...
+    },
+  ],
+});
+```
diff --git a/website/docs/en/guide/basic/_meta.json b/website/docs/en/guide/basic/_meta.json
@@ -2,9 +2,8 @@
   "cli",
   "configure-rslib",
   "typescript-usage",
-  "output-files",
-  "bundle-mode",
+  "output-format",
+  "output-structure",
   "upgrade-rslib",
-  "cjs-esm",
   "umd"
 ]
diff --git a/website/docs/en/guide/basic/bundle-mode.mdx b/website/docs/en/guide/basic/bundle-mode.mdx
diff --git a/website/docs/en/guide/basic/cjs-esm.mdx b/website/docs/en/guide/basic/cjs-esm.mdx
diff --git a/website/docs/en/guide/basic/output-files.mdx b/website/docs/en/guide/basic/output-files.mdx
diff --git a/website/docs/en/guide/basic/output-format.mdx b/website/docs/en/guide/basic/output-format.mdx
@@ -0,0 +1,98 @@
+# Output Format
+
+This sets the output format for the generated JavaScript files. There are three supported values now: `esm`, `cjs`, and `umd`. If you do not specify an output format, esbuild will choose one for you when bundling is enabled. If bundling is disabled, no format conversion will occur.
+
+{/* The library has different build methods and options. You can choose a proper build method based on the scenario. In these section, we will introduce some common build patterns and when to use them. */}
+
+## ESM / CJS
+
+Library authors need to carefully consider which module formats to support. Let's understand ESM (ECMAScript Modules) and CJS (CommonJS) and when to use them.
+
+### What are ESM and CJS?
+
+- ESM is a modern module system introduced in ES2015 that allows JavaScript code to be organized into reusable, self-contained modules. ESM is now the standard for both [browser](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) and [Node.js](https://nodejs.org/api/esm.html) environments, replacing older module systems like [CommonJS (CJS)](https://nodejs.org/api/modules.html) and [AMD](https://requirejs.org/docs/whyamd.html).
+
+- [CommonJS](https://nodejs.org/api/modules.html#modules-commonjs-modules) is a module system- used in JavaScript, particularly in server-side environments like Node.js. It was created to allow JavaScript to be used outside of the browser by providing a way to manage modules and dependencies.
+
+### What is the dilemma of esm / cjs
+
+### When to support which format?
+
+For modern libraries, it's recommended to:
+
+1. **Default to ESM**
+
+   - ESM is the future of JavaScript modules
+   - Better tree-shaking support
+   - Native browser support
+   - Top-level await support
+
+2. **Consider CJS if:**
+
+   - Supporting older Node.js versions (`<12.x`)
+   - Supporting tools/frameworks that don't fully support ESM
+   - Having users with CommonJS-only dependencies
+
+3. **Support both formats**
+
+   - To maximize compatibility, you can build both formats:
+     1. Output ESM files with `.mjs` extension
+     2. Output CJS files with `.cjs` extension
+     3. Configure package.json with:
+        ```json
+        {
+          "type": "module",
+          "exports": {
+            "import": "./dist/index.mjs",
+            "require": "./dist/index.cjs"
+          }
+        }
+        ```
+
+## UMD
+
+UMD is a library that can be used in both the browser and Node.js environments. It is a combination of CommonJS and AMD.
+
+### How to build a UMD library?
+
+- Set the `output.format` to `umd` in the Rslib configuration file.
+- If the library need to be exported with a name, set `output.umdName` to the name of the UMD library.
+- Use `output.externals` to specify the external dependencies that the UMD library depends on, `lib.autoExtension` is enabled by default for UMD.
+
+### Examples
+
+The following Rslib config is an example to build a UMD library.
+
+- `output.format: 'umd'`: instruct Rslib to build in UMD format.
+- `output.umdName: 'RslibUmdExample'`: set the export name of the UMD library.
+- `output.externals.react: 'React'`: specify the external dependency `react` could be accessed by `window.React`.
+- `runtime: 'classic'`: use the classic runtime of React to support applications that using React version under 18.
+
+```ts title="rslib.config.ts" {7-12,22}
+import { pluginReact } from '@rsbuild/plugin-react';
+import { defineConfig } from '@rslib/core';
+
+export default defineConfig({
+  lib: [
+    {
+      format: 'umd',
+      umdName: 'RslibUmdExample',
+      output: {
+        externals: {
+          react: 'React',
+        },
+        distPath: {
+          root: './dist/umd',
+        },
+      },
+    },
+  ],
+  plugins: [
+    pluginReact({
+      swcReactOptions: {
+        runtime: 'classic',
+      },
+    }),
+  ],
+});
+```
diff --git a/website/docs/en/guide/basic/output-structure.mdx b/website/docs/en/guide/basic/output-structure.mdx
@@ -0,0 +1,22 @@
+# Output Structure
+
+## bundle / bundleless
+
+So first let's understand bundle and bundleless.
+
+A bundle is a package of build artifacts, which may be a single file or multiple files based on a certain [code splitting strategy](https://esbuild.github.io/api/#splitting).
+
+bundleless, on the other hand, means that each source file is compiled and built separately, but not bundled together. Each output file can be found with its corresponding source code file. The process of **bundleless build can also be understood as the process of code conversion of source files only**.
+
+They have their own benefits.
+
+- bundle can reduce the size of build artifacts and also pre-package dependencies to reduce the size of installed dependencies. Packaging libraries in advance can speed up application project builds.
+- bundleless maintains the original file structure and is more conducive to debugging and tree shaking.
+
+:::warning
+bundleless is a single-file compilation mode, so for referencing and exporting types, you need to add the `type` keyword. For example, `import type { A } from './types'`. Please refer to [TypeScript - isolatedModules](/guide/basic/typescript#isolatedmodules) for more information.
+:::
+
+You can specify whether to bundle using the [bundle](/config/lib/bundle) option, which is set to `true` by default.
+
+## 
diff --git a/website/docs/en/guide/start/glossary.mdx b/website/docs/en/guide/start/glossary.mdx
@@ -1 +1,21 @@
 # Glossary
+
+## ESM
+
+ESM stands for ECMAScript Modules, a modern module system introduced in ES2015 that allows JavaScript code to be organized into reusable, self-contained modules. ESM is now the standard for both [browser](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) and [Node.js](https://nodejs.org/api/esm.html) environments, replacing older module systems like [CommonJS (CJS)](https://nodejs.org/api/modules.html) and [AMD](https://requirejs.org/docs/whyamd.html).
+
+## CJS
+
+CJS stands for [CommonJS](https://nodejs.org/api/modules.html#modules-commonjs-modules), a module system used in JavaScript, particularly in server-side environments like Node.js. It was created to allow JavaScript to be used outside of the browser by providing a way to manage modules and dependencies.
+
+## UMD
+
+UMD stands for [Universal Module Definition](https://github.com/umdjs/umd), a pattern for writing JavaScript modules that can work universally across different environments, such as both the browser and Node.js. Its primary goal is to ensure compatibility with the most popular module systems, including AMD (Asynchronous Module Definition), CommonJS (CJS), and browser globals.
+
+## 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.
+
+## More
+
+See more glossary in [Rsbuild - Glossary](https://rsbuild.dev/guide/start/glossary) and [Rspack - Glossary](https://rspack.dev/misc/glossary).
diff --git a/website/docs/en/guide/start/quick-start.mdx b/website/docs/en/guide/start/quick-start.mdx
@@ -23,7 +23,7 @@ nvm use --lts
 
 ## Creating an Rslib Project
 
-You can use the `create-rslib` to create a new Rslib project. Run the following command:
+You can use the [`create-rslib`](https://www.npmjs.com/package/create-rslib) to create a new Rslib project. Run the following command:
 
 import { PackageManagerTabs } from '@theme';
 
@@ -40,18 +40,37 @@ Then follow the prompts to complete the operation.
 
 ### Templates
 
-When creating a project, you can choose from the following templates provided by `create-rslib`:
+`create-rslib` 是用来快速创建 Rslib 项目的工具。在创建项目时，你可以从以下模板中选择：
 
-| Template     | Description                                        |
-| ------------ | -------------------------------------------------- |
-| node-dual-js | Node.js dual ESM/CJS package                       |
-| node-dual-ts | Node.js dual ESM/CJS package written in TypeScript |
-| node-esm-js  | Node.js pure ESM package                           |
-| node-esm-ts  | Node.js pure ESM package written in TypeScript     |
+| 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      |
+
+Each template support both use JavaScript and TypeScript.
+
+:::info
+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.
+
+- 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.
+
+```text
+◆  Select development tools (Use <space> to select, <enter> to continue)
+│  ◻ Storybook
+│  ◻ Vitest
+└
+```
 
 ### Optional Tools
 
-`create-rslib` can help you set up some commonly used tools, including [Biome](https://github.com/biomejs/biome), [ESLint](https://github.com/eslint/eslint), and [prettier](https://github.com/prettier/prettier). 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 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.
 
 ```text
 ◆  Select additional tools (Use <space> to select, <enter> to continue)

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,5 @@`
`1`	`1`	`[`
`2`	`2`	`"package-json",`
`3`		`- "templates",`
`4`	`3`	`"third-party-deps",`
`5`	`4`	`"polyfill",`
`6`	`5`	`"css",`