@modern-js/main-doc 2.69.7 → 3.0.0-alpha.1

package/docs/en/plugin/official/cli-plugins/plugin-swc.mdx

@@ -1,363 +0,0 @@
----
-sidebar_position: 2
----
-
-# SWC Plugin
-
-:::warning
-**The SWC feature in the current document is no longer maintained**, we recommend using the Rspack + SWC solution.
-
-Please refer to [「Use Rspack」](guides/advanced-features/rspack-start) for more information.
-
-:::
-
-import SWC from '@site-docs-en/components/swc.mdx';
-
-<SWC />
-
-## Usage Scenarios
-
-Before using the SWC plugin, please understand the scenarios and limitations of the SWC plugin to determine whether your project is suitable for using it.
-
-### Rspack Scenario
-
-If you are already using Rspack as the bundler in your project, then you do not need to use the SWC plugin, because Rspack uses SWC for transpiler and minifier by default, and the SWC compilation capabilities are available out of the box.
-
-If you have configured the current SWC plugin when using Rspack, it will not have any effect.
-
-### Babel Plugins
-
-If your project requires the registration of some custom Babel plugins, you will not be able to register and use Babel plugins after using SWC, since it replaces Babel as the transpiler.
-
-For most common Babel plugins, you can find corresponding replacements in SWC, such as:
-
-- `@babel/preset-env`: use [presetEnv](#presetenv) instead.
-- `@babel/preset-react`: use [presetReact](#presetreact) instead.
-- `babel-plugin-import`: use [source.transformImport](/configure/app/source/transform-import) instead.
-- `babel-plugin-lodash`: use [extensions.lodash](#extensionslodash) instead.
-- `@emotion/babel-plugin`: use [extensions.emotion](#extensionsemotion) instead.
-- `babel-plugin-styled-components`: use [extensions.styledComponents](#extensionsstyledcomponents) instead.
-- `@babel/plugin-react-transform-remove-prop-types`: use [reactUtils.removePropTypes](#extensionsreactutils) instead.
-
-If you use Babel plugin capabilities that are not yet supported by SWC, you will no longer be able to use them after switching to SWC compilation. You can give feedback via issues under the [swc-plugins](https://github.com/web-infra-dev/swc-plugins) repository and we will evaluate if built-in support is needed.
-
-### Bundle Size
-
-When using SWC for code minification instead of [terser](https://github.com/terser/terser) and [cssnano](https://github.com/cssnano/cssnano), there may be a small change in the bundle size. SWC outperforms terser for JavaScript code compression and slightly underperforms cssnano for CSS code compression.
-
-For a detailed comparison between minifiers, see [minification-benchmarks](https://github.com/privatenumber/minification-benchmarks).
-
-## Quick Start
-
-### Used in Modern.js framework
-
-The Modern.js framework integrates the SWC plugin, and you can use it in the following ways:
-
-import EnableSWC from '@site-docs-en/components/enableSwc.mdx';
-
-<EnableSWC />
-
-That's it! Now you can use SWC transformation and minification in your project.
-
-## Config
-
-- **Type:**
-
-```ts
-type PluginConfig =
-  | ObjPluginConfig
-  | ((
-      config: ObjPluginConfig,
-      utils: { mergeConfig: typeof lodash.merge; setConfig: typeof lodash.set },
-    ) => ObjPluginConfig | void);
-
-// SwcOptions is configurations of swc https://swc.rs/docs/configuration/compilation
-interface ObjPluginConfig extends SwcOptions {
-  presetReact?: ReactConfig;
-  presetEnv?: EnvConfig;
-  jsMinify?: boolean | JsMinifyOptions;
-  cssMinify?: boolean | CssMinifyOptions;
-  extensions?: Extensions;
-  overrides?: Overrides;
-}
-```
-
-The plugin configuration is based on the SWC configuration. In order to simplify some deep-level configurations and improve development experience, certain extensions have been made. When using object-based configuration, for example you can use `presetReact` and `presetEnv` to quickly configure React-related features and syntax downgrading. Other configurations will also be directly passed through to SWC.
-
-When using function-based configuration, the default configuration generated by the plugin will be passed in, allowing you to modify it or return a new configuration.
-
-### presetReact
-
-- **Type:** [presetReact](https://swc.rs/docs/configuration/compilation#jsctransformreact) in SWC.
-
-Ported from `@babel/preset-react`. The value you passed will be merged with default option.
-
-By default, the plugin will set `runtime` field based on your `react` version, if `react` version is newer than 17.0.0, it will be set to `automatic`, otherwish `classic`.
-
-### presetEnv
-
-- **Type:** [presetEnv](https://swc.rs/docs/configuration/supported-browsers#options) in SWC.
-
-Ported from `@babel/preset-env`. The value you passed will be merged with default option.
-
-Default option is:
-
-```ts
-{
-  targets: '', // automatic get browserslist from your project, so you don't have to set this field
-  mode: 'usage',
-}
-```
-
-### jsMinify
-
-- **Type:** `boolean` or [compress configuration](https://terser.org/docs/api-reference.html#compress-options).
-- **Default:** `{ compress: {}, mangle: true }`.
-
-If set it to `false`, then SWC minification will be disabled, if set it to `true` then will it applies default option. If you pass an object, then this object will be merged with default option.
-
-### cssMinify
-
-- **Type:**: `boolean`
-- **Default:**: `true`
-
-Whether enable to compress CSS files by SWC. If enabled, it will improve the performance of CSS compression, but the compression ratio will be slightly reduced.
-
-### overrides
-
-- **Type:**
-
-```ts
-interface Overrides extends SwcOptions {
-  test: RegExp;
-  include: RegExp[];
-  exclude: RegExp[];
-}
-```
-
-- **Default:** `undefined`
-
-Specify special configuration for specific modules. For example if you want to set ie 11 target for `foo.ts`:
-
-```ts
-{
-  test: /foo.ts/,
-  env: { targets: 'ie 11' }
-}
-```
-
-This will merged into the default configuration, and do not affect other modules.
-
-### extensions
-
-- **Type:** `Object`
-
-Some plugins ported from Babel.
-
-#### extensions.reactUtils
-
-- **Type:** `Object`
-
-```ts
-type ReactUtilsOptions = {
-  autoImportReact?: boolean;
-  removeEffect?: boolean;
-  removePropTypes?: {
-    mode?: 'remove' | 'unwrap' | 'unsafe-wrap';
-    removeImport?: boolean;
-    ignoreFilenames?: string[];
-    additionalLibraries?: string[];
-    classNameMatchers?: string[];
-  };
-};
-```
-
-Some little help utils for `React`.
-
-**reactUtils.autoImportReact**
-
-- **Type:** `boolean`
-
-Automatically import `React` as global variable, eg: `import React from 'react'`.
-Mostly used for generated `React.createElement`.
-
-**reactUtils.removeEffect**
-
-- **Type:** `boolean`
-
-Remove `useEffect` call.
-
-**reactUtils.removePropTypes**
-
-- **Type:**
-
-```ts
-type RemovePropTypesOptions = {
-  mode?: 'remove' | 'unwrap' | 'unsafe-wrap';
-  removeImport?: boolean;
-  ignoreFilenames?: string[];
-  additionalLibraries?: string[];
-  classNameMatchers?: string[];
-};
-```
-
-Remove `React` runtime type checking. This is ported from [@babel/plugin-react-transform-remove-prop-types](https://github.com/oliviertassinari/babel-plugin-transform-react-remove-prop-types), All the configurations remain the same.
-
-#### extensions.lodash
-
-- **Type:**
-
-```ts
-type LodashOptions = {
-  cwd?: string;
-  ids?: string[];
-};
-```
-
-- **Default:**
-
-```ts
-const defaultOptions = {
-  cwd: process.cwd(),
-  ids: ['lodash', 'lodash-es'],
-};
-```
-
-Ported from [babel-plugin-lodash](https://github.com/lodash/babel-plugin-lodash), it is used to automatically convert references to Lodash into on-demand imports, thereby reducing the bundle size of Lodash code.
-
-```ts
-// Input
-import { get, throttle } from 'lodash';
-
-// Output
-import get from 'lodash/get';
-import throttle from 'lodash/throttle';
-```
-
-#### extensions.styledComponents
-
-- **Type:**
-
-```ts
-boolean | {
-  // Enabled by default in development, disabled in production to reduce file size,
-  // setting this will override the default for all environments.
-  displayName?: boolean,
-  // Enabled by default.
-  ssr?: boolean,
-  // Enabled by default.
-  fileName?: boolean,
-  // Empty by default.
-  topLevelImportPaths?: string[],
-  // Defaults to ["index"].
-  meaninglessFileNames?: string[],
-  // Enabled by default.
-  cssProp?: boolean,
-  // Empty by default.
-  namespace?: string,
-};
-```
-
-This is ported by Next.js team from [babel-plugin-styled-components](https://github.com/styled-components/babel-plugin-styled-components).
-
-#### extensions.emotion
-
-- **Type:**
-
-```ts
-boolean | {
-  // default is true. It will be disabled when build type is production.
-  sourceMap?: boolean,
-  // default is 'dev-only'.
-  autoLabel?: 'never' | 'dev-only' | 'always',
-  // default is '[local]'.
-  // Allowed values: `[local]` `[filename]` and `[dirname]`
-  // This option only works when autoLabel is set to 'dev-only' or 'always'.
-  // It allows you to define the format of the resulting label.
-  // The format is defined via string where variable parts are enclosed in square brackets [].
-  // For example labelFormat: "my-classname--[local]", where [local] will be replaced with the name of the variable the result is assigned to.
-  labelFormat?: string,
-  // default is undefined.
-  // This option allows you to tell the compiler what imports it should
-  // look at to determine what it should transform so if you re-export
-  // Emotion's exports, you can still use transforms.
-  importMap?: {
-    [packageName: string]: {
-      [exportName: string]: {
-        canonicalImport?: [string, string],
-        styledBaseImport?: [string, string],
-      }
-    }
-  },
-}
-```
-
-This is ported by Next.js team from [@emotion/babel-plugin](https://www.npmjs.com/package/@emotion/babel-plugin)
-
-#### extensions.pluginImport
-
-:::tip
-Modern.js provides the [source.transformImport](/configure/app/source/transform-import) config, so you don't need to configure `extensions.pluginImport` manually.
-:::
-
-Ported from [babel-plugin-import](https://github.com/umijs/babel-plugin-import), configurations are the same.
-
-Some configurations can be passed in functions, such as `customName`, `customStyleName`. These JavaScript functions will be called by Rust through Node-API, which will cause some performance overhead.
-
-Some simple function logic can be replaced by template language. Therefore, the configuration of function items such as `customName`, `customStyleName` can also be passed in strings as templates to replace functions and improve performance.
-
-For example:
-
-```ts
-import { MyButton as Btn } from 'foo';
-```
-
-Apply following configurations:
-
-```ts
-PluginSWC({
-  extensions: {
-    pluginImport: [
-      {
-        libraryName: 'foo',
-        customName: 'foo/es/{{ member }}',
-      },
-    ],
-  },
-});
-```
-
-`{{ member }}` will be replaced by the imported specifier:
-
-```ts
-import Btn from 'foo/es/MyButton';
-```
-
-Template `customName: 'foo/es/{{ member }}'` is the same as `` customName: (member) => `foo/es/${member}`  ``, but template value has no performance overhead of Node-API.
-
-The template used here is [handlebars](https://handlebarsjs.com). There are some useful builtin tools, Take the above import statement as an example:
-
-```ts
-PluginSWC({
-  extensions: {
-    pluginImport: [
-      {
-        libraryName: 'foo',
-        customName: 'foo/es/{{ kebabCase member }}',
-      },
-    ],
-  },
-});
-```
-
-Transformed to:
-
-```ts
-import Btn from 'foo/es/my-button';
-```
-
-In addition to `kebabCase`, there are `cameraCase`, `snakeCase`, `upperCase` and `lowerCase` can be used as well.
-
-## Limitation
-
-Do not support `@babel/plugin-transform-runtime` and other custom Babel plugins.

package/docs/en/plugin/official/cli-plugins/plugin-tailwind.mdx

@@ -1,5 +0,0 @@
-# Tailwind CSS Plugin
-
-Tailwind CSS is a utility-first CSS framework and design system that allows you to quickly add commonly used styles to components while supporting flexible theme style extensions.
-
-For more details, refer to [Using Tailwind CSS](/guides/basic-features/css/tailwindcss).

package/docs/en/plugin/official/rsbuild-plugins/_meta.json

@@ -1 +0,0 @@
-["plugin-esbuild"]

package/docs/en/plugin/official/rsbuild-plugins/plugin-esbuild.mdx

@@ -1,205 +0,0 @@
----
-sidebar_position: 3
----
-
-# Esbuild Plugin
-
-:::warning
-**The esbuild feature in the current document is no longer maintained**, we recommend using the Rspack + SWC solution, because Rspack + SWC provide better build performance, richer features, and better compatibility.
-
-Please refer to [「Use Rspack」](guides/advanced-features/rspack-start) for more information.
-
-:::
-
-import Esbuild from '@site-docs-en/components/esbuild.mdx';
-
-<Esbuild />
-
-## Quick Start
-
-### Used in Modern.js framework
-
-The Modern.js framework integrates the esbuild plugin by default, so you don't need to manually install and register the plugin, just use the [tools.esbuild](https://modernjs.dev/en/configure/app/tools/esbuild.html) configuration:
-
-```js
-export default defineConfig({
-  tools: {
-    esbuild: {
-      loader: {
-        target: 'chrome61',
-      },
-      minimize: {
-        target: 'chrome61',
-      },
-    },
-  },
-});
-```
-
-## Config
-
-The plugin will enable code transformation and minification by default. You can also customize the behavior of the plugin through configuration.
-
-### loader
-
-- **Type:**
-
-```ts
-type LoaderOptions = EsbuildLoaderOptions | false | undefined;
-```
-
-- **Default:**
-
-```ts
-const defaultOptions = {
-  target: 'es2015',
-  charset: builderConfig.output.charset,
-};
-```
-
-This config is used to enable JavaScript/TypeScript transformation, which will replace babel-loader and ts-loader with esbuild-loader.
-
-If you want to modify the options, you can check the [esbuild-loader documentation](https://github.com/privatenumber/esbuild-loader#loader).
-
-#### Set JSX Format
-
-When using esbuild for transformation, esbuild will read the `compilerOptions.jsx` field in `tsconfig.json` to determine which JSX syntax to use.
-
-Therefore, you need to set the correct JSX syntax in `tsconfig.json`.
-
-For example, React projects need to set `compilerOptions.jsx` to `react-jsx`:
-
-```json
-{
-  "compilerOptions": {
-    "jsx": "react-jsx"
-  }
-}
-```
-
-#### Set the target environment
-
-Use the `target` option to set the target environment for transformation. `target` can be set directly to the JavaScript language version, such as `es6`, `es2020`; it can also be set to several target environments, each target environment is an environment name followed by a version number, such as `['chrome58', 'edge16' ,'firefox57']`. For a detailed introduction of the `target` option, please refer to [esbuild - target](https://esbuild.github.io/api/#target).
-
-target supports setting to the following environments:
-
-- chrome
-- edge
-- firefox
-- ie
-- ios
-- node
-- opera
-- safari
-
-```ts
-builderPluginEsbuild({
-  loader: {
-    target: 'chrome61',
-  },
-});
-```
-
-#### Disable transformation
-
-Set `loader` to `false` to disable esbuild transformation, and Modern.js will continue to use Babel to transform the code.
-
-```ts
-builderPluginEsbuild({
-  loader: false,
-});
-```
-
-### minimize
-
-- **Type:**
-
-```ts
-type MinimizeOptions = EsbuildMinifyOptions | false | undefined;
-```
-
-- **Default:**
-
-```ts
-const defaultOptions = {
-  css: true,
-  target: 'es2015',
-  format: builderTarget === 'web' ? 'iife' : undefined,
-};
-```
-
-This option is used to enable minification for JavaScript and CSS.
-
-If you want to modify the options, you can check the [esbuild-loader documentation](https://github.com/privatenumber/esbuild-loader#minifyplugin).
-
-#### Set the target environment
-
-Use the `target` option to set the target environment for minification.
-
-```ts
-builderPluginEsbuild({
-  minimize: {
-    target: 'chrome61',
-  },
-});
-```
-
-#### Disable minification
-
-Set `minimize` to `false` to disable esbuild minification, and Modern.js will continue to use Terser to minify the code.
-
-```ts
-builderPluginEsbuild({
-  minimize: false,
-});
-```
-
-## Limitations
-
-Although esbuild can significantly improve the build performance of existing webpack projects, it still has certain limitations that require special attention.
-
-### Compatibility
-
-As a compiler (i.e. `loader` capability), esbuild usually supports at least ES2015 (that is, ES6) syntax, and does not have the ability to automatically inject Polyfill.. If the production environment needs to downgrade to ES5 and below syntax, it is recommended to use SWC compilation.
-
-You can specify the target syntax version by following config:
-
-```ts
-builderPluginEsbuild({
-  loader: {
-    target: 'es2015',
-  },
-});
-```
-
-As a code minify tool (i.e. `minimize` capability), esbuild can minify the code in production environment, and usually supports ES2015 syntax at least.
-
-If you set the compressed `target` to `es5`, you need to ensure that all codes have been compiled to ES5 codes, otherwise it will cause esbuild compilation error: `Transforming 'xxx' to the configured target environment ("es5") is not supported yet `.
-
-Therefore, for projects that need to be compatible with ES5 and below syntax in the production environment, please be careful to enable the minimize capability, and it is recommended to use SWC compression.
-
-You can specify the target syntax version by following config:
-
-```js
-builderPluginEsbuild({
-  minimize: {
-    target: 'es2015',
-  },
-});
-```
-
-:::danger Caution
-Projects that need to be compatible with ES5 and below syntax in the production environment need to be careful to turn on the minimize config.
-:::
-
-### Not support Babel plugins
-
-As a compiler, the syntax transformation function of the original Babel plugins such as `babel-plugin-import` is not available after esbuild is turned on. And since the bottom layer of the plugin uses esbuild's `Transform API`, it does not support esbuild plugins to customize the compilation process.
-
-If you have requirements related to Babel plugins such as `babel-plugin-import`, you can use the SWC plugin.
-
-### Bundle Size
-
-Although the compression speed of esbuild is faster, the compression ratio of esbuild is lower than that of terser, so the bundle size will increase, please use it according to the scenes. Generally speaking, esbuild is more suitable for scenes that are not sensitive to bundle size.
-
-You can refer to [minification-benchmarks](https://github.com/privatenumber/minification-benchmarks) for a detailed comparison between minimizers.

package/docs/en/plugin/official/rsbuild-plugins.mdx

@@ -1,3 +0,0 @@
-# Overview
-
-- [@modern-js/plugin-esbuild](/plugin/official/rsbuild-plugins/plugin-esbuild): Provides esbuild compilation support.

package/docs/en/plugin/runtime-plugins/migration.mdx

@@ -1,101 +0,0 @@
-# Plugin Migration
-
-### Migration Background
-
-The Modern.js plugin system is constantly evolving.  To provide a clearer API and more powerful features, we've optimized the definition and usage of Runtime plugins. While the old plugin syntax is still partially compatible, we strongly recommend migrating according to this guide to take full advantage of the new plugin system.
-
-### Migration Steps Overview
-
-1.  **Update Plugin Type Definition:** Replace the `Plugin` type with `RuntimePluginFuture`.
-2.  **Adjust Hook Invocation:** Migrate from the `return hooks` pattern to direct `api.xxx` calls.
-3.  **Replace Changed APIs:** Refer to the detailed API mapping table and update your code.
-
-### Detailed Migration Steps
-
-#### Update Plugin Type Definition
-
-This is the first and most crucial step. It ensures that your plugin interacts correctly with the new plugin system.
-
-```typescript
-// Old Syntax
-import type { Plugin } from '@modern-js/runtime';
-
-const plugin: Plugin = { ... };
-
-// New Syntax
-import type { RuntimePluginFuture } from '@modern-js/runtime';
-
-const plugin: RuntimePluginFuture = { ... };
-```
-
-**Explanation:** The `RuntimePluginFuture` type is the standard definition for new plugins. It provides better type inference and a clearer API structure.
-
-#### Adjust Hook Invocation
-
-The new plugin system recommends using the `api` object to directly call Hooks. This approach is more intuitive and easier to maintain.
-
-```typescript
-// Old Syntax (return hooks)
-{
-  setup: () => ({
-    beforeRender({ req, res }) { /*...*/ }
-  })
-}
-
-// New Syntax (api.xxx)
-{
-  setup: api => {
-    api.onBeforeRender(({ req, res }) => { /*...*/ })
-  }
-}
-```
-
-**Explanation:** The `api` object provides all available Hooks and utility methods.
-
-#### Replace Changed APIs
-
-To maintain API consistency and clarity, we've adjusted the names of some APIs.  Additionally, the `hoc` and `init` Hooks have been removed. Please use the new Hooks as replacements. The table below lists all changed APIs and their old and new counterparts:
-
-| Old API       | New API           | Description                                                                                                                                                                                                                                                                                                 |
-| :------------ | :---------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `beforeRender` | `onBeforeRender`  | Executed before application rendering.                                                                                                                                                                                                                                                                        |
-| `hoc`         | `wrapRoot`        | **Important Change:** Used to wrap the root component, achieving the functionality of a Higher-Order Component (HOC).  Make sure to pass props to the original component.                                                                                                                                    |
-| `init`        | `onBeforeRender`  | **Important Change:**  Execute initialization logic before application rendering. This replaces the previous `init` hook. Use `onBeforeRender` to perform any setup or initialization tasks that were previously done in `init`.  This provides a single, consistent point for pre-rendering logic. |
-
-**Explanation:**
-- `onBeforeRender` replaces both the original `beforeRender` and `init`, used for pre-rendering logic and initialization, respectively.
-- `wrapRoot` replaces `hoc` and is used to implement higher-order component functionality.  It's crucial to pass props correctly when using `wrapRoot`.
-
-**`wrapRoot` Usage Example:**
-
-```typescript
-{
-  setup: api => {
-    api.wrapRoot((App) => {
-      const AppWrapper = (props) => {
-        // Ensure props are passed to the original component
-        return <Provider value={xx}><App {...props}/></Provider>;
-      };
-      return AppWrapper;
-    });
-  }
-}
-```
-
-### Frequently Asked Questions
-
-**Q: Will my plugin still work correctly after migration?**
-
-A: As long as you've correctly completed all the steps in this guide, your plugin should function properly. If you encounter any issues, please refer to the official Modern.js documentation or seek community support.
-
-**Q: Do I have to migrate my plugin immediately?**
-
-A: While the old plugin syntax remains partially compatible, we strongly recommend migrating as soon as possible. The new plugin system offers improved performance and richer functionality, making migration worthwhile in the long run.
-
-**Q: Where can I find more information about the new plugin system?**
-
-A: Please consult the official Modern.js documentation, especially the section on the plugin system. You can also refer to examples of other migrated plugins to understand best practices.
-
-### Summary
-
-With this detailed migration guide, we hope to help you smoothly transition your Runtime plugins to the new Modern.js plugin system. If you encounter any problems during the migration process, please don't hesitate to ask for assistance.