@modern-js/main-doc 2.69.5 → 3.0.0-alpha.0

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/tutorials/first-app/c01-start.mdx

@@ -1,99 +0,0 @@
----
-title: Create Project
----
-# Create Project
-
-Starting from this chapter, we will enter the practical tutorial section. In the practical tutorial, we will start with environment preparation, starting from simple to complex, building a real project step by step.
-
-## Environment preparation
-
-import Prerequisites from "@site-docs-en/components/prerequisites"
-
-<Prerequisites />
-
-## Initialization project
-
-We create a new directory and initialize the project via the command line tool:
-
-```bash
-mkdir myapp && cd myapp
-npx @modern-js/create@latest
-```
-
-import InitApp from "@site-docs-en/components/init-app"
-
-<InitApp />
-
-## Debug Project
-
-import DebugApp from "@site-docs-en/components/debug-app"
-
-<DebugApp />
-
-## Modify the code
-
-We delete the original sample code and replace it with a simple point of contact list:
-
-```tsx title="src/routes/page.tsx"
-const getAvatar = (users: Array<{ name: string; email: string }>) =>
-  users.map(user => ({
-    ...user,
-    avatar: `https://api.dicebear.com/7.x/pixel-art/svg?seed=${user.name}`,
-  }));
-
-const mockData = getAvatar([
-  { name: 'Thomas', email: 'w.kccip@bllmfbgv.dm' },
-  { name: 'Chow', email: 'f.lfqljnlk@ywoefljhc.af' },
-  { name: 'Bradley', email: 'd.wfovsqyo@gpkcjwjgb.fr' },
-  { name: 'Davis', email: '"t.kqkoj@utlkwnpwk.nu' },
-]);
-
-function App() {
-  return (
-    <ul>
-      {mockData.map(({ name, avatar, email }) => (
-        <li key={name}>
-          <img src={avatar} width={60} height={60} /> ---
-          <span>{name}</span> ---
-          <span>{email}</span>
-        </li>
-      ))}
-    </ul>
-  );
-}
-
-export default App;
-```
-
-Remove redundant css files and keep the directory free of redundant files:
-
-```bash
-rm src/routes/index.css
-```
-
-Since the framework supports [HMR](https://webpack.js.org/concepts/hot-module-replacement/) by default, you can see that the content in http://localhost:8080/ is automatically updated to:
-
-![result](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvt/ljhwZthlaukjlkulzlp/screenshot-20221214-141909.png)
-
-The page has no styles at the moment. The next chapter will expand on this section.
-
-## Enable SSR
-
-Next, we modify the `modern.config.ts` in the project to enable the SSR capability:
-
-```ts
-import { appTools, defineConfig } from '@modern-js/app-tools';
-
-export default defineConfig({
-  runtime: {
-    router: true,
-    state: true,
-  },
-  server: {
-    ssr: true,
-  },
-  plugins: [appTools()],
-});
-```
-
-Re-execute `pnpm run dev` to find that the project has completed page rendering at the server level.

package/docs/en/tutorials/first-app/c02-component.mdx

@@ -1,60 +0,0 @@
----
-title: Add UI Components
----
-
-# Add UI Components
-
-In the previous chapter, we learned how to initialize a project and use configuration to modify the default behavior of Modern.js.
-
-In this chapter, we continue to use the project code of the previous chapter and continue to improve the point of contact list.
-
-In order to do better UI display and interaction, we introduce the component library [Antd](https://ant.design/index-cn) to develop, and use the `<List>` component instead of the primitive list. Add dependency first:
-
-import { PackageManagerTabs } from '@theme';
-
-<PackageManagerTabs command="add antd" />
-
-Modify `src/routes/page.tsx` to import components at the top:
-
-```ts
-import { List } from 'antd';
-```
-
-Modify the implementation of the `<App>` component:
-
-```tsx
-function App() {
-  return (
-    <div>
-      <List
-        dataSource={mockData}
-        renderItem={({ name, email, avatar }) => (
-          <List.Item key={name}>
-            <List.Item.Meta
-              avatar={<img alt="avatar" src={avatar} width={60} height={60} />}
-              title={name}
-              description={email}
-            />
-          </List.Item>
-        )}
-      />
-    </div>
-  );
-}
-```
-
-Execute `pnpm run dev` to see the running results:
-
-![result](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/modern-website/tutorials/c02-antd-result.png)
-
-You can see that the components exported by Ant Design already have complete styles.
-
-:::info note
-Modern.js [Automatically import CSS required by Ant Design component on demand](https://github.com/ant-design/babel-plugin-import).
-
-:::
-
-:::note
-We can also use other component libraries to implement the same functionality, such as [Arco Design](https://arco.design/).
-
-:::

package/docs/en/tutorials/first-app/c03-css.mdx

@@ -1,324 +0,0 @@
----
-title: Add Style
----
-
-# Add Style
-
-import { Tabs, Tab as TabItem } from '@theme';
-
-In the previous chapter, we learned how to use components from the third-party library.
-
-In this chapter, we will learn how to implement UI components.
-
-## JS components using CSS
-
-First of all, we want to control the display of contact avatars by ourselves, and implement this design draft:
-
-![design](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/modern-website/tutorials/c03-css-expect.jpg)
-
-Hypothesis has no ready-made components to implement, so you need to write some CSS yourself. Here we use [styled-components](https://styled-components.com/) to implement similar requirements. Modern.js out of the box supports styled-components, which requires neither dependency nor configuration.
-
-Style-components avoids many problems of traditional CSS writing through modularization. For example, writing styles directly on the style attribute of elements, the visual details of UI will also be mixed with the details of UI structure and business logic. Or classname needs to avoid global space renaming, which requires the use of naming conventions.
-
-Modify the code at the top in `src/routes/page.tsx`:
-
-```js
-import styled from '@modern-js/runtime/styled';
-```
-
-Add the following code:
-
-```js
-const Avatar = styled.img`
-  width: 50px;
-  height: 50px;
-  border: 4px solid #0ef;
-  border-radius: 50%;
-`;
-```
-
-Modify the code of `List.Item.Meta`:
-
-```tsx
-<List.Item.Meta
-  avatar={<Avatar src={avatar} />}
-  title={name}
-  description={email}
-/>
-```
-
-Execute `pnpm run dev` to see the expected running result:
-
-![result](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/modern-website/tutorials/c03-css-result1.png)
-
-Next we do a little refactoring. To enhance legibility and make the code easier to maintain, we can split the Avatar component. We execute the following command at the end point to create a new file:
-
-<Tabs>
-<TabItem value="macOS" label="macOS" default>
-
-```bash
-mkdir -p src/components/Avatar
-touch src/components/Avatar/index.tsx
-```
-
-</TabItem>
-<TabItem value="Windows" label="Windows">
-
-```powershell
-mkdir -p src/components/Avatar
-ni src/components/Avatar/index.tsx
-```
-
-</TabItem>
-</Tabs>
-
-Delete the `<Avatar>` implementation in `src/routes/page.tsx` and change it to:
-
-```ts
-import Avatar from '../components/Avatar';
-```
-
-The content of `src/components/Avatar/index.tsx` is modified to:
-
-```ts
-import styled from '@modern-js/runtime/styled';
-
-const Avatar = styled.img`
-  width: 50px;
-  height: 50px;
-  border: 4px solid #0ef;
-  border-radius: 50%;
-`;
-
-export default Avatar;
-```
-
-Execute `pnpm run dev`, the result should be the same.
-
-:::info note
-The reason for using the directory form `Avatar/index.tsx` instead of the single-file form `Avatar.tsx` is that you can easily add sub-files inside the directory later, including dedicated resources (pictures, etc.), dedicated sub-components, CSS files, etc.
-
-:::
-
-## Utility
-
-We have used the style-components implementation `<Avatar>` component, but the current UI is still unsatisfactory and lacks professionalism, such as the list item inhouse layout is a bit rough and misaligned in many places.
-
-Now, let's implement a better `Item` component ourselves, implementing a design draft like this:
-
-![design](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/06/design2.png)
-
-The UI to be implemented this time is more complex and has an internal structure, but on the other hand, there is no very thick bright blue border of the `<Avatar>` component such a very special UI, which is a very conventional horizontal and vertical layout, centering, font style, etc. In this case, there is actually no need to write CSS at all. There is a more efficient implementation method that complements styled-components: **Utility Class**.
-
-Modern.js integrates the mainstream, light, general-purpose Utility Class library [Tailwind CSS](https://tailwindcss.com/).
-
-Execute `pnpm run new` and select the following to start Tailwind CSS:
-
-```bash
-? Please select the operation you want: Enable features
-? Please select the feature name: Enable Tailwind CSS
-```
-
-Register the Tailwind plugin in `modern.config.ts`:
-
-```ts title="modern.config.ts"
-import { appTools, defineConfig } from '@modern-js/app-tools';
-import { tailwindcssPlugin } from '@modern-js/plugin-tailwindcss';
-
-export default defineConfig({
-  runtime: {
-    router: true,
-    state: true,
-  },
-  server: {
-    ssr: true,
-  },
-  plugins: [appTools(), tailwindcssPlugin()],
-});
-```
-
-Import the Tailwind CSS css file at the top of `src/routes/page.tsx` to start a quick implementation of the professional UI:
-
-```js
-import 'tailwindcss/base.css';
-import 'tailwindcss/components.css';
-import 'tailwindcss/utilities.css';
-```
-
-Create the Item component first:
-
-<Tabs>
-<TabItem value="macOS" label="macOS" default>
-
-```bash
-mkdir -p src/components/Item
-touch src/components/Item/index.tsx
-```
-
-</TabItem>
-<TabItem value="Windows" label="Windows">
-
-```powershell
-mkdir -p src/components/Item
-ni src/components/Item/index.tsx
-```
-
-</TabItem>
-</Tabs>
-
-Modify `src/routes/page.tsx` to pass the `render` implementation of `List` to `Item` component:
-
-```js
-import { List } from 'antd';
-import 'tailwindcss/base.css';
-import 'tailwindcss/components.css';
-import 'tailwindcss/utilities.css';
-import Item from '../components/Item';
-
-const getAvatar = (users: Array<{ name: string, email: string }>) =>
-  users.map(user => ({
-    ...user,
-    avatar: `https://api.dicebear.com/7.x/pixel-art/svg?seed=${user.name}`,
-  }));
-
-const mockData = getAvatar([
-  { name: 'Thomas', email: 'w.kccip@bllmfbgv.dm' },
-  { name: 'Chow', email: 'f.lfqljnlk@ywoefljhc.af' },
-  { name: 'Bradley', email: 'd.wfovsqyo@gpkcjwjgb.fr' },
-  { name: 'Davis', email: '"t.kqkoj@utlkwnpwk.nu' },
-]);
-
-function Index() {
-  return (
-    <div className="container lg mx-auto">
-      <List
-        dataSource={mockData}
-        renderItem={info => <Item key={info.name} info={info} />}
-      />
-    </div>
-  );
-}
-
-export default Index;
-```
-
-Utility Class(https://tailwindcss.com/docs/container) is used on the parent container for a quick implementation of the most basic maximum width, center, and other styles.
-
-Next implementation `src/components/Item/index.tsx`:
-
-```tsx
-import Avatar from '../Avatar';
-
-type InfoProps = {
-  avatar: string;
-  name: string;
-  email: string;
-  archived?: boolean;
-};
-
-const Item = ({ info }: { info: InfoProps }) => {
-  const { avatar, name, email, archived } = info;
-  return (
-    <div className="flex p-4 items-center border-gray-200 border-b">
-      <Avatar src={avatar} />
-      <div className="ml-4 flex-1 flex justify-between">
-        <div className="flex-1">
-          <p>{name}</p>
-          <p>{email}</p>
-        </div>
-        <button
-          type="button"
-          disabled={archived}
-          className={`bg-blue-500  text-white font-bold
-            py-2 px-4 rounded-full hover:bg-blue-700`}
-        >
-          Archive
-        </button>
-      </div>
-    </div>
-  );
-};
-
-export default Item;
-```
-
-Execute `pnpm run dev` to see the expected running result:
-
-![result](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/06/result2.png)
-
-We only use a few Utility Classes, such as [Flex](https://tailwindcss.com/docs/display/), [Padding](https://tailwindcss.com/docs/padding/), [Margin](https://tailwindcss.com/docs/margin/), [Text](https://tailwindcss.com/docs/text-color/), [Font](https://tailwindcss.com/docs/font-weight/), [Border](https://tailwindcss.com/docs/border-width), without writing a single CSS implementation Professional UI that conforms to the design draft.
-
-## Customized Utility Class
-
-We can also implement the new Utility Class ourselves to facilitate reuse between codes.
-
-Utility Class itself is also a **component-oriented** technology (using different classes on a component is equivalent to setting some attributes from the base class for this component), but the classname of Utility Class is global (because it is used on arbitrary components/elements), it is very suitable for implementation with separate CSS files.
-
-Create a new CSS file:
-
-<Tabs>
-<TabItem value="macOS" label="macOS" default>
-
-```bash
-mkdir -p src/styles
-touch src/styles/utils.css
-```
-
-</TabItem>
-<TabItem value="Windows" label="Windows">
-
-```powershell
-mkdir -p src/styles
-ni src/styles/utils.css
-```
-
-</TabItem>
-</Tabs>
-
-Import `utils.css` in `src/routes/page.tsx`:
-
-```js
-import '../styles/utils.css';
-```
-
-A Utility Class named `custom-text-gray` is implemented in `src/routes/styles/utils.css`.
-
-```css
-:root {
-  --custom-text-color: rgb(113, 128, 150);
-}
-
-.custom-text-gray {
-  color: var(--custom-text-color);
-}
-```
-
-:::info note
-Modern.js integrates with [PostCSS](/guides/basic-features/css/css) and supports modern CSS syntax features such as [custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties).
-
-:::
-
-Use in `src/components/Item/index.tsx`:
-
-```js
-<div className="ml-4 flex-1 flex justify-between">
-```
-
-Change to:
-
-```js
-<div className="ml-4 custom-text-gray flex-1 flex justify-between">
-```
-
-Execute `pnpm run dev`, you can see that the font color has changed:
-
-![design2](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/06/result3.png)
-
-:::info note
-This is just to demonstrate Utility Class usage. In a real project, with Tailwind CSS, this Utility Class is of little value and should be added to the font color through the [**theme**](https://tailwindcss.com/docs/customizing-colors) of the configuration Design System.
-
-`utils.css` can also be written as `utils.scss` or `utils.less`, Modern.js out of the box support for SCSS and Less.
-
-However, with the support of PostCSS, modern CSS should be sufficient to meet these development needs, and the performance is also better than that of the preprocessor. It is recommended to use `.css` files first.
-
-:::