feat: improve description, types and JSDoc for entry options (#8361)

* feat: improve description, types and JSDoc for entry options

* fix

* docs: update

packages/rspack/src/builtin-plugin/EntryPlugin.ts

@@ -5,30 +5,29 @@ import {
 } from "@rspack/binding";
 
 import {
-	type ChunkLoading,
-	type EntryRuntime,
-	type Filename,
-	type Layer,
-	type LibraryOptions,
-	type PublicPath,
+	type EntryDescriptionNormalized,
 	getRawChunkLoading,
 	getRawLibrary
 } from "../config";
 import { isNil } from "../util";
 import { create } from "./base";
 
-export type EntryOptions = {
+/**
+ * Options for the `EntryPlugin`.
+ */
+export type EntryOptions = Omit<EntryDescriptionNormalized, "import"> & {
+	/**
+	 * The name of the entry chunk.
+	 */
 	name?: string;
-	runtime?: EntryRuntime;
-	chunkLoading?: ChunkLoading;
-	asyncChunks?: boolean;
-	publicPath?: PublicPath;
-	baseUri?: string;
-	filename?: Filename;
-	library?: LibraryOptions;
-	layer?: Layer;
-	dependOn?: string[];
 };
+
+/**
+ * The entry plugin that will handle creation of the `EntryDependency`.
+ * It adds an entry chunk on compilation. The chunk is named `options.name` and
+ * contains only one module (plus dependencies). The module is resolved from
+ * `entry` in `context` (absolute path).
+ */
 export const EntryPlugin = create(
 	BuiltinPluginName.EntryPlugin,
 	(

packages/rspack/src/config/normalization.ts

@@ -11,9 +11,7 @@
 import type { Compilation } from "../Compilation";
 import type {
 	AssetModuleFilename,
-	AsyncChunks,
 	Bail,
-	BaseUri,
 	CacheOptions,
 	ChunkFilename,
 	ChunkLoading,
@@ -31,8 +29,7 @@ import type {
 	DevtoolNamespace,
 	EnabledLibraryTypes,
 	EnabledWasmLoadingTypes,
-	EntryFilename,
-	EntryRuntime,
+	EntryDescription,
 	EntryStatic,
 	Environment,
 	Externals,
@@ -53,7 +50,6 @@ import type {
 	ImportMetaName,
 	Incremental,
 	InfrastructureLogging,
-	Layer,
 	LazyCompilationOptions,
 	LibraryOptions,
 	Loader,
@@ -459,18 +455,21 @@ export type EntryNormalized = EntryDynamicNormalized | EntryStaticNormalized;
 export interface EntryStaticNormalized {
 	[k: string]: EntryDescriptionNormalized;
 }
-export interface EntryDescriptionNormalized {
+
+export type EntryDescriptionNormalized = Pick<
+	EntryDescription,
+	| "runtime"
+	| "chunkLoading"
+	| "asyncChunks"
+	| "publicPath"
+	| "baseUri"
+	| "filename"
+	| "library"
+	| "layer"
+> & {
 	import?: string[];
-	runtime?: EntryRuntime;
-	chunkLoading?: ChunkLoading;
-	asyncChunks?: AsyncChunks;
-	publicPath?: PublicPath;
-	baseUri?: BaseUri;
-	filename?: EntryFilename;
-	library?: LibraryOptions;
 	dependOn?: string[];
-	layer?: Layer;
-}
+};
 
 export interface OutputNormalized {
 	path?: Path;

packages/rspack/src/config/types.ts

@@ -167,10 +167,14 @@ export type EntryItem = string | string[];
 /** The entry that the current entry depends on. With dependOn option you can share the modules from one entry chunk to another. */
 export type EntryDependOn = string | string[];
 
+/**
+ * An object with entry point description.
+ */
 export type EntryDescription = {
 	/**
 	 * The path to the entry module.
 	 * @default './src/index.js'
+	 * @example ['./src/index.js', './src/foo.js']
 	 * */
 	import: EntryItem;
 
@@ -199,13 +203,23 @@ export type EntryDescription = {
 	/** The filename of the entry chunk. */
 	filename?: EntryFilename;
 
-	/** The format of the chunk generated by this entry as a library. */
+	/**
+	 * The format of the chunk generated by this entry as a library.
+	 * For detailed configuration, see `output.library`.
+	 */
 	library?: LibraryOptions;
 
-	/** The entry that the current entry depends on. With dependOn option you can share the modules from one entry chunk to another. */
+	/**
+	 * The entry that the current entry depends on. With `dependOn` option
+	 * you can share the modules from one entry chunk to another.
+	 */
 	dependOn?: EntryDependOn;
 
-	/** The layer of this entry, make the corresponding configuration take effect through layer matching in SplitChunks, Rules, Stats, and Externals. */
+	/**
+	 * Specifies the layer in which modules of this entrypoint are placed.
+	 * Make the corresponding configuration take effect through layer matching
+	 * in split chunks, rules, stats, and externals.
+	 */
 	layer?: Layer;
 };
 

website/docs/en/config/entry.mdx

@@ -93,7 +93,29 @@ When you set `entry` to an object, you can set the value of the entry to a descr
   defaultValueList={[{ defaultValue: "'./src/index.js'" }]}
 />
 
-The path to the entry module.
+The path or paths to the entry modules.
+
+```ts title="rspack.config.js"
+module.exports = {
+  entry: {
+    foo: {
+      import: './src/foo.js',
+    },
+  },
+};
+```
+
+Multiple paths can be set in the `import` property:
+
+```ts title="rspack.config.js"
+module.exports = {
+  entry: {
+    foo: {
+      import: ['./src/foo.js', './src/bar.js'],
+    },
+  },
+};
+```
 
 #### EntryDescription.runtime
 
@@ -124,7 +146,7 @@ module.exports = {
   defaultValueList={[{ defaultValue: 'undefined' }]}
 />
 
-How this entry load other chunks.
+How this entry load other chunks. Methods included by default are `'jsonp'` (web), `'import'` (ESM), `'import-scripts'` (WebWorker), `'require'` (sync node.js), `'async-node'` (async node.js), but others might be added by plugins.
 
 #### EntryDescription.asyncChunks
 
@@ -200,7 +222,7 @@ The default value can be affected by different [target](/config/target):
   defaultValueList={[{ defaultValue: 'undefined' }]}
 />
 
-The layer of this entry, make the corresponding configuration take effect through layer matching in split chunks, [rules](/config/module#ruleissuerlayer), stats, and externals.
+Specifies the layer in which modules of this entrypoint are placed. Make the corresponding configuration take effect through layer matching in split chunks, [rules](/config/module#ruleissuerlayer), stats, and externals.
 
 :::warning
 This configuration will only take effect when [experiments.layers](/config/experiments#experimentslayers) is `true`.

website/docs/en/plugins/webpack/entry-plugin.mdx

@@ -27,13 +27,16 @@ To adjust settings related to the entry module.
 - **Type:**
 
 ```ts
-type EntryOptions = {
-  name?: string;
-  runtime?: EntryRuntime;
-  chunkLoading?: ChunkLoading;
-  asyncChunks?: boolean;
-  publicPath?: PublicPath;
-  baseUri?: string;
-  filename?: Filename;
-};
+type EntryOptions =
+  | string
+  | (Omit<EntryDescriptionNormalized, 'import'> & {
+      /**
+       * The name of the entry chunk.
+       */
+      name?: string;
+    });
 ```
+
+If `options` is a string, its value will be used as `name`.
+
+Please refer to [Entry Description Object](/config/entry#entry-description-object) for all available options.

website/docs/zh/config/entry.mdx

@@ -93,7 +93,29 @@ module.exports = {
   defaultValueList={[{ defaultValue: "'./src/index.js'" }]}
 />
 
-入口模块的路径。
+一个或多个入口模块的路径。
+
+```ts title="rspack.config.js"
+module.exports = {
+  entry: {
+    foo: {
+      import: './src/foo.js',
+    },
+  },
+};
+```
+
+`import` 属性可以设置多个路径：
+
+```ts title="rspack.config.js"
+module.exports = {
+  entry: {
+    foo: {
+      import: ['./src/foo.js', './src/bar.js'],
+    },
+  },
+};
+```
 
 #### EntryDescription.runtime
 
@@ -124,7 +146,7 @@ module.exports = {
   defaultValueList={[{ defaultValue: 'undefined' }]}
 />
 
-设置当前入口在加载 chunk 时的加载方式。
+设置当前入口在加载 chunk 时的加载方式。默认包含的方式有 `'jsonp'` (web), `'import'` (ESM), `'import-scripts'` (WebWorker), `'require'` (sync node.js), `'async-node'` (async node.js)，其他方式可由插件提供。
 
 #### EntryDescription.asyncChunks
 
@@ -200,7 +222,7 @@ module.exports = {
   defaultValueList={[{ defaultValue: 'undefined' }]}
 />
 
-设置当前入口的 Layer，以在 split chunks, [rules](/config/module#ruleissuerlayer)、stats、externals 中通过 layer 匹配使对应的配置生效。
+指定当前入口的模块所在的 layer。用于在 split chunks, [rules](/config/module#ruleissuerlayer)、stats、externals 中通过 layer 匹配使对应的配置生效。
 
 :::warning
 只有在 [experiments.layers = true](/config/experiments#experimentslayers) 时该配置才会生效。

website/docs/zh/plugins/webpack/entry-plugin.mdx

@@ -27,13 +27,16 @@ new rspack.EntryPlugin(context, entry, options);
 - **Type:**
 
 ```ts
-type EntryOptions = {
-  name?: string;
-  runtime?: EntryRuntime;
-  chunkLoading?: ChunkLoading;
-  asyncChunks?: boolean;
-  publicPath?: PublicPath;
-  baseUri?: string;
-  filename?: Filename;
-};
+type EntryOptions =
+  | string
+  | (Omit<EntryDescriptionNormalized, 'import'> & {
+      /**
+       * The name of the entry chunk.
+       */
+      name?: string;
+    });
 ```
+
+当 `options` 为字符串时，它的值会被作为 `name` 使用。
+
+请参考 [入口描述对象](/config/entry#入口描述对象) 了解所有可用的选项。