@bleedingdev/modern-js-app-tools 3.9.0-ultramodern.8 → 3.9.3-ultramodern.1

package/dist/types/types/plugin-base.d.ts

@@ -0,0 +1,188 @@
+import type { ResolvedDeployTarget } from '@modern-js/app-tools-extensions/deploy-output/target';
+import type { AppContext, AsyncHook, CLIPluginExtends, InternalContext, PluginHook, PluginHookTap, TransformFunction } from '@modern-js/plugin/cli';
+import type { BffRuntimeFramework } from '@modern-js/plugin/server';
+import type { Entrypoint, HtmlPartials, HtmlTemplates, RouteLegacy } from '@modern-js/types/cli/base';
+import type { ServerPlugin } from '@modern-js/types/common';
+import type { HttpMethodDecider, ServerRoute } from '@modern-js/types/server';
+import type { EagerRouteComponentFilesByEntry } from '@modern-js/utils/route-component-files';
+import type { EnvironmentConfig } from '@rsbuild/core';
+export type AppToolsModuleType = 'module' | 'commonjs';
+export type AppToolsHookRunners = Record<string, any>;
+export interface BffCompilation {
+    readonly appDirectory: string;
+    readonly apiDirectory: string;
+    readonly sourceDirectories: readonly string[];
+    readonly outputDirectories: readonly string[];
+    readonly distDirectory: string;
+    readonly tsconfigPath?: string;
+    readonly moduleType: AppToolsModuleType;
+}
+export interface BffGeneration {
+    readonly appDirectory: string;
+    readonly apiDirectory: string;
+    readonly lambdaDirectory: string;
+    readonly existLambda: boolean;
+    readonly apiFiles: readonly string[];
+    readonly relativeDistPath: string;
+    readonly prefix: string;
+    readonly port?: number;
+    readonly requestId: string;
+    readonly requestCreator?: string;
+    readonly httpMethodDecider?: HttpMethodDecider;
+}
+export interface BffClientArtifact {
+    /** Canonical relative source path under generation.apiDirectory. */
+    readonly sourcePath: string;
+    readonly code: string;
+    readonly declaration: string;
+}
+export interface BffClientArtifacts {
+    readonly generation: BffGeneration;
+    additionalArtifacts: BffClientArtifact[];
+}
+export interface BffGeneratedModule {
+    readonly code: string;
+    readonly declaration: string;
+}
+export interface BffGeneratedEntries {
+    readonly generation: BffGeneration;
+    plugin: BffGeneratedModule;
+    runtime: BffGeneratedModule | null;
+    /** Direct dependencies required by the emitted SDK modules. */
+    packageDependencies: Record<string, string>;
+}
+export type BeforeBffCompileFn = (context: BffCompilation) => void | Promise<void>;
+export type AfterBffCompileFn = (context: BffCompilation) => void | Promise<void>;
+export type ModifyBffClientArtifactsFn = TransformFunction<BffClientArtifacts>;
+export type ModifyBffGeneratedEntriesFn = TransformFunction<BffGeneratedEntries>;
+export type AfterPrepareFn = () => Promise<void> | void;
+export type CheckEntryPointFn = TransformFunction<{
+    path: string;
+    entry: false | string;
+}>;
+export type ModifyEntrypointsFn = TransformFunction<{
+    entrypoints: Entrypoint[];
+}>;
+export type ModifyBuilderEnvironmentsFn = TransformFunction<{
+    environments: Record<string, EnvironmentConfig>;
+}>;
+export type ModifyFileSystemRoutesFn<Routes> = TransformFunction<{
+    entrypoint: Entrypoint;
+    routes: RouteLegacy[] | Routes[];
+}>;
+export type DeplpoyFn = () => Promise<void> | void;
+export type GenerateEntryCodeFn = (params: {
+    entrypoints: Entrypoint[];
+}) => Promise<void> | void;
+export type BeforeGenerateRoutesFn = TransformFunction<{
+    entrypoint: Entrypoint;
+    code: string;
+}>;
+export type BeforePrintInstructionsFn = TransformFunction<{
+    instructions: string;
+}>;
+export type AddRuntimeExportsFn = () => Promise<void> | void;
+export interface AppToolsExtendAPIBase<Extends extends CLIPluginExtends, Routes> {
+    onAfterPrepare: PluginHookTap<AfterPrepareFn>;
+    deploy: PluginHookTap<DeplpoyFn>;
+    checkEntryPoint: PluginHookTap<CheckEntryPointFn>;
+    modifyEntrypoints: PluginHookTap<ModifyEntrypointsFn>;
+    modifyBuilderEnvironments: PluginHookTap<ModifyBuilderEnvironmentsFn>;
+    modifyFileSystemRoutes: PluginHookTap<ModifyFileSystemRoutesFn<Routes>>;
+    generateEntryCode: PluginHookTap<GenerateEntryCodeFn>;
+    onBeforeGenerateRoutes: PluginHookTap<BeforeGenerateRoutesFn>;
+    /**
+     * @deprecated
+     */
+    onBeforePrintInstructions: PluginHookTap<BeforePrintInstructionsFn>;
+    /**
+     * @deprecated use getAppContext instead
+     */
+    useAppContext: () => AppContext<Extends> & Extends['extendContext'];
+    /**
+     * @deprecated use getConfig instead
+     */
+    useConfigContext: () => Extends['config'];
+    /**
+     * @deprecated use getNormalizedConfig instead
+     */
+    useResolvedConfigContext: () => Extends['normalizedConfig'];
+    /**
+     * @deprecated use api.xx instead
+     */
+    useHookRunners: () => AppToolsHookRunners;
+}
+export interface AppToolsExtendHooksBase<Routes> extends Record<string, PluginHook<(...args: any[]) => any>> {
+    onBeforeBffCompile: AsyncHook<BeforeBffCompileFn>;
+    onAfterBffCompile: AsyncHook<AfterBffCompileFn>;
+    modifyBffClientArtifacts: AsyncHook<ModifyBffClientArtifactsFn>;
+    modifyBffGeneratedEntries: AsyncHook<ModifyBffGeneratedEntriesFn>;
+    onAfterPrepare: AsyncHook<AfterPrepareFn>;
+    deploy: AsyncHook<DeplpoyFn>;
+    checkEntryPoint: AsyncHook<CheckEntryPointFn>;
+    modifyEntrypoints: AsyncHook<ModifyEntrypointsFn>;
+    modifyBuilderEnvironments: AsyncHook<ModifyBuilderEnvironmentsFn>;
+    modifyFileSystemRoutes: AsyncHook<ModifyFileSystemRoutesFn<Routes>>;
+    generateEntryCode: AsyncHook<GenerateEntryCodeFn>;
+    onBeforeGenerateRoutes: AsyncHook<BeforeGenerateRoutesFn>;
+    /**
+     * @deprecated
+     */
+    onBeforePrintInstructions: AsyncHook<BeforePrintInstructionsFn>;
+}
+export interface AppToolsExtendContextBase<Extends extends CLIPluginExtends> {
+    metaName: string;
+    internalDirectory: string;
+    sharedDirectory: string;
+    internalDirAlias: string;
+    internalSrcAlias: string;
+    apiDirectory: string;
+    lambdaDirectory: string;
+    runtimeConfigFile: string;
+    serverPlugins: ServerPlugin[];
+    moduleType: AppToolsModuleType;
+    /** Exact generated files excluded from server compilation. */
+    serverCompileExcludedFiles?: string[];
+    /** Information for entry points */
+    entrypoints: Entrypoint[];
+    /** Selected entry points */
+    checkedEntries: string[];
+    /** Information for server routes */
+    serverRoutes: ServerRoute[];
+    /** Whether to use api only mode */
+    apiOnly: boolean;
+    deployTarget: ResolvedDeployTarget;
+    _internalContext: InternalContext<Extends>;
+    /**
+     * Information for HTML templates by entry
+     * @private
+     */
+    partialsByEntrypoint?: Record<string, HtmlPartials>;
+    /**
+     * Information for HTML templates
+     * @private
+     */
+    htmlTemplates: HtmlTemplates;
+    /**
+     * @deprecated compat old plugin, default is app tools
+     */
+    toolsType?: string;
+    /**
+     * Identification for bff runtime framework
+     * @private
+     */
+    bffRuntimeFramework?: BffRuntimeFramework;
+    /**
+     * Route component files collected from the FINAL file-system routes (after all
+     * `modifyFileSystemRoutes` consumers ran), keyed by entry name. Populated by
+     * the router plugin during route generation and consumed (currently by stream
+     * SSR lazy compilation) to force route component chunks eager.
+     *
+     * Published via the app context (`api.updateAppContext`) by the router plugin,
+     * then read fresh when assembling the builder options and threaded into
+     * `BuilderOptions.eagerRouteComponentFilesByEntry`; the SSR builder plugin
+     * reads it from those options (not from the context directly).
+     * @private
+     */
+    eagerRouteComponentFilesByEntry?: EagerRouteComponentFilesByEntry;
+}

package/dist/types/types/plugin.d.ts

@@ -1,188 +1,14 @@
-import type { AppContext, AsyncHook, InternalContext, PluginHook, PluginHookTap, TransformFunction } from '@modern-js/plugin';
-import type { Hooks } from '@modern-js/plugin/cli';
-import type { BffRuntimeFramework } from '@modern-js/plugin/server';
-import type { Entrypoint, HtmlPartials, HtmlTemplates, HttpMethodDecider, NestedRouteForCli, PageRoute, RouteLegacy, ServerPlugin, ServerRoute } from '@modern-js/types';
-import type { EagerRouteComponentFilesByEntry } from '@modern-js/utils';
-import type { EnvironmentConfig } from '@rsbuild/core';
-import type { getHookRunners } from '../compat/hooks.js';
-import type { AppTools } from './index.js';
-import type { AppToolsNormalizedConfig, AppToolsUserConfig } from './config/index.js';
-export interface BffCompilation {
-    readonly appDirectory: string;
-    readonly apiDirectory: string;
-    readonly sourceDirectories: readonly string[];
-    readonly outputDirectories: readonly string[];
-    readonly distDirectory: string;
-    readonly tsconfigPath?: string;
-    readonly moduleType: AppToolsContext['moduleType'];
+import type { AppContext, Hooks } from '@modern-js/plugin/cli';
+import type { NestedRouteForCli, PageRoute } from '@modern-js/types/cli';
+import type { AppTools, AppToolsNormalizedConfig, AppToolsUserConfig } from './config/index.js';
+import type { AppToolsExtendAPIBase, AppToolsExtendContextBase, AppToolsExtendHooksBase, ModifyFileSystemRoutesFn as BaseModifyFileSystemRoutesFn } from './plugin-base.js';
+export * from './plugin-base.js';
+export type ModifyFileSystemRoutesFn = BaseModifyFileSystemRoutesFn<NestedRouteForCli | PageRoute>;
+export interface AppToolsExtendAPI extends AppToolsExtendAPIBase<AppTools, NestedRouteForCli | PageRoute> {
 }
-export interface BffGeneration {
-    readonly appDirectory: string;
-    readonly apiDirectory: string;
-    readonly lambdaDirectory: string;
-    readonly existLambda: boolean;
-    readonly apiFiles: readonly string[];
-    readonly relativeDistPath: string;
-    readonly prefix: string;
-    readonly port?: number;
-    readonly requestId: string;
-    readonly requestCreator?: string;
-    readonly httpMethodDecider?: HttpMethodDecider;
+export interface AppToolsExtendHooks extends AppToolsExtendHooksBase<NestedRouteForCli | PageRoute> {
 }
-export interface BffClientArtifact {
-    /** Canonical relative source path under generation.apiDirectory. */
-    readonly sourcePath: string;
-    readonly code: string;
-    readonly declaration: string;
-}
-export interface BffClientArtifacts {
-    readonly generation: BffGeneration;
-    additionalArtifacts: BffClientArtifact[];
-}
-export interface BffGeneratedModule {
-    readonly code: string;
-    readonly declaration: string;
-}
-export interface BffGeneratedEntries {
-    readonly generation: BffGeneration;
-    plugin: BffGeneratedModule;
-    runtime: BffGeneratedModule | null;
-    /** Direct dependencies required by the emitted SDK modules. */
-    packageDependencies: Record<string, string>;
-}
-export type BeforeBffCompileFn = (context: BffCompilation) => void | Promise<void>;
-export type AfterBffCompileFn = (context: BffCompilation) => void | Promise<void>;
-export type ModifyBffClientArtifactsFn = TransformFunction<BffClientArtifacts>;
-export type ModifyBffGeneratedEntriesFn = TransformFunction<BffGeneratedEntries>;
-export type AfterPrepareFn = () => Promise<void> | void;
-export type CheckEntryPointFn = TransformFunction<{
-    path: string;
-    entry: false | string;
-}>;
-export type ModifyEntrypointsFn = TransformFunction<{
-    entrypoints: Entrypoint[];
-}>;
-export type ModifyBuilderEnvironmentsFn = TransformFunction<{
-    environments: Record<string, EnvironmentConfig>;
-}>;
-export type ModifyFileSystemRoutesFn = TransformFunction<{
-    entrypoint: Entrypoint;
-    routes: RouteLegacy[] | (NestedRouteForCli | PageRoute)[];
-}>;
-export type DeplpoyFn = () => Promise<void> | void;
-export type GenerateEntryCodeFn = (params: {
-    entrypoints: Entrypoint[];
-}) => Promise<void> | void;
-export type BeforeGenerateRoutesFn = TransformFunction<{
-    entrypoint: Entrypoint;
-    code: string;
-}>;
-export type BeforePrintInstructionsFn = TransformFunction<{
-    instructions: string;
-}>;
-export type AddRuntimeExportsFn = () => Promise<void> | void;
-export interface AppToolsExtendAPI {
-    onAfterPrepare: PluginHookTap<AfterPrepareFn>;
-    deploy: PluginHookTap<DeplpoyFn>;
-    checkEntryPoint: PluginHookTap<CheckEntryPointFn>;
-    modifyEntrypoints: PluginHookTap<ModifyEntrypointsFn>;
-    modifyBuilderEnvironments: PluginHookTap<ModifyBuilderEnvironmentsFn>;
-    modifyFileSystemRoutes: PluginHookTap<ModifyFileSystemRoutesFn>;
-    generateEntryCode: PluginHookTap<GenerateEntryCodeFn>;
-    onBeforeGenerateRoutes: PluginHookTap<BeforeGenerateRoutesFn>;
-    /**
-     * @deprecated
-     */
-    onBeforePrintInstructions: PluginHookTap<BeforePrintInstructionsFn>;
-    /**
-     * @deprecated use getAppContext instead
-     */
-    useAppContext: () => AppToolsContext;
-    /**
-     * @deprecated use getConfig instead
-     */
-    useConfigContext: () => AppToolsUserConfig;
-    /**
-     * @deprecated use getNormalizedConfig instead
-     */
-    useResolvedConfigContext: () => AppToolsNormalizedConfig<AppToolsUserConfig>;
-    /**
-     * @deprecated use api.xx instead
-     */
-    useHookRunners: () => ReturnType<typeof getHookRunners>;
-}
-export interface AppToolsExtendHooks extends Record<string, PluginHook<(...args: any[]) => any>> {
-    onBeforeBffCompile: AsyncHook<BeforeBffCompileFn>;
-    onAfterBffCompile: AsyncHook<AfterBffCompileFn>;
-    modifyBffClientArtifacts: AsyncHook<ModifyBffClientArtifactsFn>;
-    modifyBffGeneratedEntries: AsyncHook<ModifyBffGeneratedEntriesFn>;
-    onAfterPrepare: AsyncHook<AfterPrepareFn>;
-    deploy: AsyncHook<DeplpoyFn>;
-    checkEntryPoint: AsyncHook<CheckEntryPointFn>;
-    modifyEntrypoints: AsyncHook<ModifyEntrypointsFn>;
-    modifyBuilderEnvironments: AsyncHook<ModifyBuilderEnvironmentsFn>;
-    modifyFileSystemRoutes: AsyncHook<ModifyFileSystemRoutesFn>;
-    generateEntryCode: AsyncHook<GenerateEntryCodeFn>;
-    onBeforeGenerateRoutes: AsyncHook<BeforeGenerateRoutesFn>;
-    /**
-     * @deprecated
-     */
-    onBeforePrintInstructions: AsyncHook<BeforePrintInstructionsFn>;
-}
-export interface AppToolsExtendContext {
-    metaName: string;
-    internalDirectory: string;
-    sharedDirectory: string;
-    internalDirAlias: string;
-    internalSrcAlias: string;
-    apiDirectory: string;
-    lambdaDirectory: string;
-    runtimeConfigFile: string;
-    serverPlugins: ServerPlugin[];
-    moduleType: 'module' | 'commonjs';
-    /** Exact generated files excluded from server compilation. */
-    serverCompileExcludedFiles?: string[];
-    /** Information for entry points */
-    entrypoints: Entrypoint[];
-    /** Selected entry points */
-    checkedEntries: string[];
-    /** Information for server routes */
-    serverRoutes: ServerRoute[];
-    /** Whether to use api only mode */
-    apiOnly: boolean;
-    _internalContext: InternalContext<AppTools>;
-    /**
-     * Information for HTML templates by entry
-     * @private
-     */
-    partialsByEntrypoint?: Record<string, HtmlPartials>;
-    /**
-     * Information for HTML templates
-     * @private
-     */
-    htmlTemplates: HtmlTemplates;
-    /**
-     * @deprecated compat old plugin, default is app tools
-     */
-    toolsType?: string;
-    /**
-     * Identification for bff runtime framework
-     * @private
-     */
-    bffRuntimeFramework?: BffRuntimeFramework;
-    /**
-     * Route component files collected from the FINAL file-system routes (after all
-     * `modifyFileSystemRoutes` consumers ran), keyed by entry name. Populated by
-     * the router plugin during route generation and consumed (currently by stream
-     * SSR lazy compilation) to force route component chunks eager.
-     *
-     * Published via the app context (`api.updateAppContext`) by the router plugin,
-     * then read fresh when assembling the builder options and threaded into
-     * `BuilderOptions.eagerRouteComponentFilesByEntry`; the SSR builder plugin
-     * reads it from those options (not from the context directly).
-     * @private
-     */
-    eagerRouteComponentFilesByEntry?: EagerRouteComponentFilesByEntry;
+export interface AppToolsExtendContext extends AppToolsExtendContextBase<AppTools> {
 }
 export type AppToolsContext = AppContext<AppTools> & AppToolsExtendContext;
 export type AppToolsHooks = Hooks<AppToolsUserConfig, AppToolsNormalizedConfig, {}, {}> & AppToolsExtendHooks;

package/dist/types/utils/initAppContext.d.ts

@@ -13,7 +13,7 @@ export declare const initAppContext: ({ metaName, appDirectory, runtimeConfigFil
     tempDir?: string;
 }) => {
     runtimeConfigFile: string;
-    ip: any;
+    ip: string | undefined;
     port: number;
     moduleType: any;
     apiDirectory: string;
@@ -28,5 +28,5 @@ export declare const initAppContext: ({ metaName, appDirectory, runtimeConfigFil
     apiOnly: boolean;
     internalDirAlias: string;
     internalSrcAlias: string;
-    bffRuntimeFramework: "hono";
+    bffRuntimeFramework: keyof import("@modern-js/plugin/server").BffRuntimeRegistry;
 };

package/docs/apis/app/commands.md

@@ -227,6 +227,7 @@ Usage: modern deploy [options]
 Options:
   -c --config <config>  Specify configuration file path, either relative or absolute
   -s --skip-build       Skip the build stage
+  --deploy-target <target>  Deploy target (node, vercel, netlify, ghPages, cloudflare); overrides deploy.target and MODERNJS_DEPLOY
   -h, --help            Display command help
 ```
 

package/docs/configure/app/bff/effect.md

@@ -51,7 +51,7 @@ the framework use the same Effect instance. Before setting
 `/effect-edge` or `/effect-client`, install the exact cohort:
 
 ```bash
-pnpm add effect@4.0.0-rc.112 @effect/opentelemetry@4.0.0-rc.112
+pnpm add effect@4.0.0-rc.117 @effect/opentelemetry@4.0.0-rc.117
 ```
 
 The pin is exact because UltraModern ships Effect as one lockstep cohort. Apps
@@ -227,14 +227,10 @@ through `pnpm-workspace.yaml` overrides. For the current UltraModern cohort,
 generated apps use:
 
 ```yaml
-trustPolicyExclude:
-  - 'effect@4.0.0-rc.112'
-  - '@effect/opentelemetry@4.0.0-rc.112'
-
 overrides:
-  '@effect/opentelemetry': 4.0.0-rc.112
-  '@effect/vitest': 4.0.0-rc.112
-  effect: 4.0.0-rc.112
+  '@effect/opentelemetry': 4.0.0-rc.117
+  '@effect/vitest': 4.0.0-rc.117
+  effect: 4.0.0-rc.117
 ```
 
 Do not add a different direct `effect` version in an app package. A mismatched
@@ -242,10 +238,7 @@ Effect prerelease can fail while building layers or HTTP middleware because runt
 services come from different package instances. The strict 24-hour release-age
 gate applies to installed packages; the current cohort has no Effect age
 exemption, and override-only `@effect/vitest` is not an installed approval
-target. `trustPolicyExclude` is a separate policy:
-its exact `effect` and `@effect/opentelemetry` exceptions cover their
-trusted-publisher to provenance metadata transition and are not release-age
-approvals.
+target.
 
 ## Contract tests
 

package/docs/configure/app/output/disable-svgr.md

@@ -5,6 +5,10 @@
 - **Type:** `boolean`
 - **Default:** `false`
 
+:::warning Deprecated
+`output.disableSvgr` is deprecated and will be removed in the next major version. Replace `output.disableSvgr: true` with [tools.svgr](/configure/app/tools/svgr.md) set to `false`; `output.disableSvgr: false` is the default behavior and can simply be removed. When both are set, `tools.svgr` wins.
+:::
+
 Whether to transform SVGs into React components. If true, will treat all .svg files as assets.
 
 By default, when an SVG resource is referenced in a JS file, Modern.js will call SVGR to convert the SVG into a React component. If you are sure that all SVG resources in your project are not being used as React components, you can turn off this conversion by setting `disableSvgr` to true to improve build performance.

package/docs/configure/app/output/svg-default-export.md

@@ -5,6 +5,10 @@
 - **Type:** `'url' | 'component'`
 - **Default:** `'url'`
 
+:::warning Deprecated
+`output.svgDefaultExport` is deprecated and will be removed in the next major version. Use `svgrOptions.exportType` of [tools.svgr](/configure/app/tools/svgr.md) instead: `'component'` maps to `exportType: 'default'`, `'url'` maps to `exportType: 'named'`. When both are set, `tools.svgr` wins.
+:::
+
 `output.svgDefaultExport` is used to configure the default export type of SVG files.
 
 When `output.svgDefaultExport` is set to `url` , the default export of SVG files is the URL of the file. For example:

package/docs/configure/app/source/react-compiler.md

@@ -9,6 +9,8 @@ Whether to enable [React Compiler](https://react.dev/learn/react-compiler). Reac
 
 Modern.js implements this capability based on the Rust-based React Compiler built into Rspack's `builtin:swc-loader` (equivalent to setting SWC's `jsc.transform.reactCompiler`), reusing Rspack's built-in SWC transform chain without introducing Babel.
 
+The compiler only runs for browser environments (`output.target: 'web'`). Server environments (`node`, the `web-worker` SSR worker and BFF code) render once per request and gain nothing from memoization, so they are never compiled.
+
 :::tip
 This option is disabled by default. It must be enabled explicitly for any React version, including React 19.
 :::

package/docs/configure/app/tools/less.md

@@ -7,49 +7,78 @@
 
 ```js
 const defaultOptions = {
-  lessOptions: {
-    javascriptEnabled: true,
+  lessLoaderOptions: {
+    lessOptions: {
+      javascriptEnabled: true,
+    },
+    // CSS Source Map enabled by default in development environment
+    sourceMap: isDev,
   },
-  // CSS Source Map enabled by default in development environment
-  sourceMap: isDev,
 };
 ```
 
-You can modify the config of [less-loader](https://github.com/webpack-contrib/less-loader) via `tools.less`.
+`tools.less` modifies the options of [@rsbuild/plugin-less](https://rsbuild.rs/plugins/list/plugin-less). It accepts the full plugin options:
+
+| Option              | Description                                                                                         |
+| ------------------- | --------------------------------------------------------------------------------------------------- |
+| `lessLoaderOptions` | Options passed to [less-loader](https://github.com/webpack-contrib/less-loader), object or function |
+| `include`           | Files handled by less-loader, defaults to `/\.less$/`                                               |
+| `exclude`           | Files that less-loader should skip                                                                  |
+| `parallel`          | Whether to compile Less modules in worker threads, defaults to `false`                              |
+
+### Modifying less-loader options
 
-### Object Type
+When `lessLoaderOptions` is an `Object`, it is merged with the default config through Object.assign in a shallow way. It should be noted that `lessOptions` is merged through deepMerge in a deep way. For example:
+
+```js
+export default {
+  tools: {
+    less: {
+      lessLoaderOptions: {
+        lessOptions: {
+          javascriptEnabled: false,
+        },
+      },
+    },
+  },
+};
+```
 
-When `tools.less` is configured as `Object` type, it is merged with the default config through Object.assign in a shallow way. It should be noted that `lessOptions` is merged through deepMerge in a deep way. For example:
+When `lessLoaderOptions` is a `Function`, the default config is passed as the first parameter, which can be directly modified or returned as the final result. The second parameter provides some utility functions that can be called directly. For example:
 
 ```js
 export default {
   tools: {
     less: {
-      lessOptions: {
-        javascriptEnabled: false,
+      lessLoaderOptions(config) {
+        // Modify the config of lessOptions
+        config.lessOptions = {
+          javascriptEnabled: false,
+        };
       },
     },
   },
 };
 ```
 
-### Function Type
+### Parallel compilation
 
-When `tools.less` is a Function, the default config is passed as the first parameter, which can be directly modified or returned as the final result. The second parameter provides some utility functions that can be called directly. For example:
+Less compilation is pure JavaScript and runs on the Node.js main thread by default. With `parallel` enabled, Less modules are compiled in a pool of worker threads, which shortens the build when a project has many Less files.
 
 ```js
 export default {
   tools: {
-    less(config) {
-      // Modify the config of lessOptions
-      config.lessOptions = {
-        javascriptEnabled: false,
-      };
+    less: {
+      parallel: true,
     },
   },
 };
 ```
 
+:::tip
+Options sent to worker threads must satisfy the [structured clone algorithm](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm). With `parallel` enabled, `lessLoaderOptions` therefore cannot contain functions, such as an `additionalData` function or a custom `implementation`.
+:::
+
 ### Modifying Less Version
 
 In some scenarios, if you need to use a specific version of Less instead of the built-in Less v4 in Modern.js, you can install the desired Less version in your project and set it up using the `implementation` option of the `less-loader`.
@@ -58,7 +87,9 @@ In some scenarios, if you need to use a specific version of Less instead of the
 export default {
   tools: {
     less: {
-      implementation: require('less'),
+      lessLoaderOptions: {
+        implementation: require('less'),
+      },
     },
   },
 };
@@ -75,8 +106,52 @@ Used to specify which files `less-loader` does not compile, You can pass in one
 ```js
 export default {
   tools: {
-    less(config, { addExcludes }) {
-      addExcludes(/node_modules/);
+    less: {
+      lessLoaderOptions(config, { addExcludes }) {
+        addExcludes(/node_modules/);
+      },
+    },
+  },
+};
+```
+
+The plugin's `exclude` option is the recommended equivalent:
+
+```js
+export default {
+  tools: {
+    less: {
+      exclude: /node_modules/,
+    },
+  },
+};
+```
+
+### Legacy form
+
+:::warning Do not mix the two layers
+As soon as an object contains a plugin-level key (`lessLoaderOptions`, `include`, `exclude`, ...), the whole object is parsed as plugin options and any loader option in it has no effect. For example, `lessOptions` in `tools.less: { parallel: true, lessOptions: { ... } }` is ignored and must be moved under `lessLoaderOptions`; a hint is printed in development.
+:::
+
+In earlier versions, `tools.less` took the less-loader options directly, e.g. `tools.less: { lessOptions: {} }` or `tools.less(config, { addExcludes }) {}`. This form still works: Modern.js wraps it into `lessLoaderOptions` and produces exactly the same config as before. A migration hint is printed in development, and the legacy form will be removed in the next major version.
+
+```js
+// legacy
+export default {
+  tools: {
+    less: {
+      lessOptions: { javascriptEnabled: false },
+    },
+  },
+};
+
+// current
+export default {
+  tools: {
+    less: {
+      lessLoaderOptions: {
+        lessOptions: { javascriptEnabled: false },
+      },
     },
   },
 };