docs: update structure / format / 3rd deps / glossary / TS

Author: fi3ework

packages/core/src/types/config/index.ts

@@ -41,6 +41,7 @@ export type AutoExternal =
   | boolean
   | {
       dependencies?: boolean;
+      optionalDependencies?: boolean;
       devDependencies?: boolean;
       peerDependencies?: boolean;
     };

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,

scripts/dictionary.txt

@@ -131,6 +131,7 @@ unencapsulated
 unocss
 unpatch
 unplugin
+unpredictibly
 unshift
 upath
 vitest

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

@@ -1,6 +1,5 @@
 [
   "package-json",
-  "templates",
   "third-party-deps",
   "polyfill",
   "css",

website/docs/en/guide/advanced/templates.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"`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/],
+      },
+      // ...
+    },
+  ],
+});
+```

website/docs/en/guide/advanced/third-party-deps.mdx

@@ -1,10 +1,9 @@
 [
   "cli",
   "configure-rslib",
-  "typescript-usage",
-  "output-files",
-  "bundle-mode",
+  "typescript",
+  "output-format",
+  "output-structure",
   "upgrade-rslib",
-  "cjs-esm",
   "umd"
 ]