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

package/docs/en/guides/upgrade/entry.mdx

@@ -0,0 +1,463 @@
+# Entry Changes
+
+This chapter introduces changes related to page entries when upgrading from Modern.js 2.0 to 3.0.
+
+## Overview
+
+Modern.js 3.0 has optimized and simplified the entry mechanism. The main changes include:
+
+- **Entry File Naming Change**: Custom entry files changed from `index.[jt]sx` to `entry.[jt]sx`
+- **Bootstrap Function Replacement**: Use the new `createRoot` and `render` APIs
+- **Runtime Configuration Migration**: `App.config` and `config` exports from `routes/layout` need to be migrated
+- **Initialization Logic Migration**: `App.init` and `init` exports from `routes/layout` need to be changed to runtime plugins
+
+## Entry Type Identification
+
+Before starting migration, first identify the entry type used in your project.
+
+### Entry Identification Conditions
+
+Modern.js scans directories and identifies entries that meet **any** of the following conditions:
+
+1. **Has a `routes/` directory** → Convention-based routing entry
+2. **Has an `App.[jt]sx?` file** → Self-controlled routing entry
+3. **Has an `index.[jt]sx?` file (2.0) or `entry.[jt]sx?` file (3.0)** → Custom entry
+
+### Single Entry vs Multiple Entries
+
+**Single Entry Application**: Scans the `src/` directory by default
+
+```bash
+src/
+├── routes/        # or
+├── App.tsx        # or
+└── index.tsx      # 2.0 version
+```
+
+**Multiple Entry Application**: Scans first-level subdirectories under `src/`
+
+```bash
+src/
+├── entry1/
+│   └── routes/    # Each subdirectory is an entry
+└── entry2/
+    └── App.tsx
+```
+
+:::tip
+You can modify the entry scanning directory through the [source.entriesDir](/configure/app/source/entries-dir) configuration.
+:::
+
+## Migration Steps
+
+The migration operations in this section only need to be performed when the corresponding usage actually exists in the project, such as `bootstrap` function, `App.config/App.init`, `config/init` functions in `routes/layout.tsx`, etc.
+
+### 1. Custom Entry File Rename
+
+If your project uses a custom entry file (`index.[jt]sx`), you need to rename it to `entry.[jt]sx`.
+
+**2.0 Version:**
+
+```bash
+src/
+└── index.tsx
+```
+
+**3.0 Version:**
+
+```bash
+src/
+└── entry.tsx
+```
+
+### 2. Bootstrap Function Migration
+
+If your entry file exports a function that receives `App` and `bootstrap` parameters, you need to use the new API instead.
+
+**2.0 Version:**
+
+```tsx title="src/index.tsx"
+export default (App: React.ComponentType, bootstrap: () => void) => {
+  // Perform initialization operations
+  initSomething().then(() => {
+    bootstrap();
+  });
+};
+```
+
+**3.0 Version:**
+
+```tsx title="src/entry.tsx"
+import { createRoot } from '@modern-js/runtime/react';
+import { render } from '@modern-js/runtime/browser';
+
+// Create root component
+const ModernRoot = createRoot();
+
+// Perform initialization operations
+async function beforeRender() {
+  await initSomething();
+}
+
+// Render application
+beforeRender().then(() => {
+  render(<ModernRoot />);
+});
+```
+
+:::info Note
+
+- The component returned by `createRoot()` corresponds to the component generated by the `routes/` directory or exported by `App.tsx`
+- The `render()` function is used to handle rendering and mounting components
+
+:::
+
+### 3. App.config Migration
+
+If you defined `App.config` in `App.[tj]sx`, you need to migrate it to the runtime configuration file.
+
+**2.0 Version:**
+
+```tsx title="src/App.tsx"
+const App = () => {
+  return <div>Hello</div>;
+};
+
+App.config = {
+  router: {
+    supportHtml5History: true,
+  },
+};
+
+export default App;
+```
+
+**3.0 Version:**
+
+Create `modern.runtime.ts` in the same directory as the entry:
+
+```ts title="src/modern.runtime.ts"
+import { defineRuntimeConfig } from '@modern-js/runtime';
+
+export default defineRuntimeConfig({
+  router: {
+    supportHtml5History: true,
+  },
+});
+```
+
+:::warning Note
+Modern.js 3.0 no longer supports configuring runtime in `modern.config.ts`, you must use the `modern.runtime.ts` file.
+:::
+
+### 4. App.init Migration
+
+If you defined `App.init` in `App.[tj]sx`, you need to change it to a runtime plugin.
+
+**2.0 Version:**
+
+```tsx title="src/App.tsx"
+const App = () => {
+  return <div>Hello</div>;
+};
+
+App.init = context => {
+  context.store = createStore();
+  context.request = (url: string) => fetch(url);
+};
+
+export default App;
+```
+
+**3.0 Version:**
+
+```ts title="src/modern.runtime.ts"
+import type { RuntimePlugin } from '@modern-js/runtime';
+import { defineRuntimeConfig } from '@modern-js/runtime';
+
+const initPlugin = (): RuntimePlugin => ({
+  name: 'init-plugin',
+  setup: api => {
+    return {
+      init({ context }) {
+        context.store = createStore();
+        context.request = (url: string) => fetch(url);
+      },
+    };
+  },
+});
+
+export default defineRuntimeConfig({
+  plugins: [initPlugin()],
+});
+```
+
+### 5. config Export Migration from routes/layout.tsx
+
+If you exported a `config` function in `routes/layout.tsx`, you need to migrate it to the runtime configuration file.
+
+**2.0 Version:**
+
+```tsx title="src/routes/layout.tsx"
+export const config = () => {
+  return {
+    router: {
+      supportHtml5History: true,
+    },
+  };
+};
+
+export default function Layout() {
+  return <Outlet />;
+}
+```
+
+**3.0 Version:**
+
+```tsx title="src/routes/layout.tsx"
+export default function Layout() {
+  return <Outlet />;
+}
+```
+
+```ts title="src/modern.runtime.ts"
+import { defineRuntimeConfig } from '@modern-js/runtime';
+
+export default defineRuntimeConfig({
+  router: {
+    supportHtml5History: true,
+  },
+});
+```
+
+### 6. init Export Migration from routes/layout.tsx
+
+If you exported an `init` function in `routes/layout.tsx`, you need to change it to a runtime plugin.
+
+**2.0 Version:**
+
+```tsx title="src/routes/layout.tsx"
+export const init = context => {
+  context.request = (url: string) => fetch(url);
+};
+
+export default function Layout() {
+  return <Outlet />;
+}
+```
+
+**3.0 Version:**
+
+```tsx title="src/routes/layout.tsx"
+export default function Layout() {
+  return <Outlet />;
+}
+```
+
+```ts title="src/modern.runtime.ts"
+import type { RuntimePlugin } from '@modern-js/runtime';
+import { defineRuntimeConfig } from '@modern-js/runtime';
+
+const initPlugin = (): RuntimePlugin => ({
+  name: 'init-plugin',
+  setup: api => {
+    return {
+      init({ context }) {
+        context.request = (url: string) => fetch(url);
+      },
+    };
+  },
+});
+
+export default defineRuntimeConfig({
+  plugins: [initPlugin()],
+});
+```
+
+## Multi-Entry Application Migration Notes
+
+For multi-entry applications, you need to use function-form configuration in `src/modern.runtime.ts`, returning different runtime configurations based on entry names.
+
+### Configuration Method
+
+**Directory Structure:**
+
+```bash
+src/
+├── modern.runtime.ts  # Unified runtime configuration file
+├── entry1/
+│   └── routes/
+└── entry2/
+    └── App.tsx
+```
+
+**Configuration Example:**
+
+```ts title="src/modern.runtime.ts"
+import { defineRuntimeConfig } from '@modern-js/runtime';
+
+export default defineRuntimeConfig(entryName => {
+  // Common configuration
+  const commonConfig = {
+    plugins: [commonPlugin()],
+  };
+
+  // Return specific configuration based on entry name
+  if (entryName === 'entry1') {
+    return {
+      ...commonConfig,
+      router: {
+        supportHtml5History: true,
+      },
+      plugins: [...commonConfig.plugins, entry1Plugin()],
+    };
+  }
+
+  if (entryName === 'entry2') {
+    return {
+      ...commonConfig,
+      router: {
+        supportHtml5History: false,
+      },
+      plugins: [...commonConfig.plugins, entry2Plugin()],
+    };
+  }
+
+  // Default configuration
+  return commonConfig;
+});
+```
+
+:::info Note
+
+- The `entryName` parameter corresponds to the entry directory name
+- Main entry (same name as `name` in `package.json`): the directory name is passed in
+- Other entries: the entry directory name is passed in
+
+:::
+
+### Migration Notes
+
+1. **Merge configurations for the same entry**: If both `App.config/App.init` and `config/init` from `routes/layout.tsx` exist for the same entry, you need to merge them into the corresponding entry configuration in the `src/modern.runtime.ts` file
+
+2. **Multiple plugins in parallel**: Multiple runtime plugins can be configured in parallel in the `plugins` array
+
+3. **Clean up old code**: After migration is complete, remember to delete from the original files:
+   - `App.config` property
+   - `App.init` method
+   - `config` export from `routes/layout.tsx`
+   - `init` export from `routes/layout.tsx`
+
+### Migration Example
+
+Assume you have a 2.0 version multi-entry application:
+
+**2.0 Version Directory Structure:**
+
+```bash
+src/
+├── main/
+│   ├── routes/
+│   │   └── layout.tsx  # Contains config and init
+│   └── App.tsx         # Contains App.config and App.init
+└── admin/
+    └── routes/
+        └── layout.tsx  # Contains config and init
+```
+
+**2.0 Version Configuration:**
+
+```tsx title="src/main/App.tsx"
+const App = () => <div>Main App</div>;
+
+App.config = {
+  router: { supportHtml5History: true },
+};
+
+App.init = context => {
+  context.mainData = 'main';
+};
+```
+
+```tsx title="src/admin/routes/layout.tsx"
+export const config = () => ({
+  router: { supportHtml5History: false },
+});
+
+export const init = context => {
+  context.adminData = 'admin';
+};
+```
+
+**3.0 Version After Migration:**
+
+```bash
+src/
+├── modern.runtime.ts  # New unified configuration file
+├── main/
+│   ├── routes/
+│   │   └── layout.tsx  # Removed config and init
+│   └── App.tsx         # Removed App.config and App.init
+└── admin/
+    └── routes/
+        └── layout.tsx  # Removed config and init
+```
+
+```ts title="src/modern.runtime.ts"
+import { defineRuntimeConfig } from '@modern-js/runtime';
+import type { RuntimePlugin } from '@modern-js/runtime';
+
+// Main entry initialization plugin
+const mainInitPlugin = (): RuntimePlugin => ({
+  name: 'main-init-plugin',
+  setup: api => {
+    return {
+      init({ context }) {
+        context.mainData = 'main';
+      },
+    };
+  },
+});
+
+// Admin entry initialization plugin
+const adminInitPlugin = (): RuntimePlugin => ({
+  name: 'admin-init-plugin',
+  setup: api => {
+    return {
+      init({ context }) {
+        context.adminData = 'admin';
+      },
+    };
+  },
+});
+
+export default defineRuntimeConfig(entryName => {
+  if (entryName === 'main') {
+    return {
+      router: {
+        supportHtml5History: true,
+      },
+      plugins: [mainInitPlugin()],
+    };
+  }
+
+  if (entryName === 'admin') {
+    return {
+      router: {
+        supportHtml5History: false,
+      },
+      plugins: [adminInitPlugin()],
+    };
+  }
+
+  return {};
+});
+```
+
+## Related Links
+
+- [Page Entries](/guides/concept/entries)
+- [Runtime Configuration](/configure/app/runtime/0-intro)
+- [Runtime Plugins](/plugin/introduction.html#runtime-插件)
+- [source.entries Configuration](/configure/app/source/entries)
+- [source.entriesDir Configuration](/configure/app/source/entries-dir)

package/docs/en/guides/upgrade/other.mdx

@@ -0,0 +1,83 @@
+# Other Important Changes
+
+This document introduces other important incompatible changes and related migration instructions when upgrading from Modern.js 2.0 to 3.0.
+
+## Webpack Build No Longer Supported
+
+Modern.js 3.0 no longer supports using webpack as a build tool, and uses Rspack as the default build bundler. Rspack is implemented in Rust, providing significant build speed improvements compared to webpack, while being highly compatible with webpack configuration, allowing most configurations to be migrated directly.
+
+If your project previously used webpack-specific configurations or plugins, you need to check if there are webpack-related custom configurations in the project and confirm whether the webpack plugins used have corresponding Rspack versions.
+
+:::tip
+Rspack is highly compatible with webpack configuration, and in most cases it can be used without modification.
+:::
+
+## Entry Name Change
+
+Modern.js 3.0 changed the default entry name to `index`, and the default built HTML file is `index.html`. `index.html` is the default homepage file for most web servers and requires no additional configuration.
+
+If your project's deployment configuration specifies a particular entry file name, you need to update it to `index.html`.
+
+## API Import Paths
+
+Modern.js 3.0 has adjusted some runtime paths, and related import paths need to be updated. The path mapping is as follows:
+
+| Old Path | New Path | Description |
+|---------|---------|------|
+| `@modern-js/runtime/bff` | `@modern-js/plugin-bff/runtime` | BFF runtime path |
+| `@modern-js/runtime/server` | `@modern-js/server-runtime` | Server-side runtime path |
+
+## Pages Directory Convention-Based Routing No Longer Supported
+
+Modern.js 3.0 no longer supports the `pages` directory convention-based routing introduced in Modern.js 1.0, and now uniformly uses the `routes` directory convention-based routing.
+
+If your project uses the `pages` directory, you need to rename the `src/pages` directory to `src/routes` and update all import paths in the project that reference the `pages` directory. For detailed migration steps, please refer to the [Convention-Based Routing documentation](/guides/basic-features/routes/routes).
+
+## SSR Mode Default Value Change
+
+Modern.js 3.0 changed the default value of `server.ssr.mode` from `'string'` to `'stream'`. This means that when SSR is enabled, streaming rendering is used by default instead of traditional string rendering.
+
+For React 18 and above projects, changing the value of `ssr.mode` from `'stream'` to `'string'` has no impact on the rendering result if you don't modify the code in Data Loader or use Suspense. If your project depends on React 17, please manually set the value of `ssr.mode` to `'string'`.
+
+## Using React Router v7
+
+Modern.js 3.0 uses React Router v7 as the default routing library. React Router v7 has only a few [incompatible changes](https://reactrouter.com/upgrading/v6) compared to v6.
+
+If you need to use React Router v5 or React Router v6, you need to use **self-controlled routing** mode. Self-controlled routing allows you to fully control routing configuration without being limited by Modern.js convention-based routing.
+
+## Using @modern-js/create to Create Monorepo and Modern.js Module
+
+Modern.js 3.0 no longer supports creating Monorepo projects and Modern.js Module projects through `@modern-js/create`.
+
+**Changes**:
+
+- In [v2.53.0](https://github.com/web-infra-dev/modern.js/releases/tag/v2.53.0), the functionality to create Monorepo projects using `@modern-js/create` was removed
+- In [v2.61.0](https://github.com/web-infra-dev/modern.js/releases/tag/v2.61.0), the functionality to create Modern.js Module projects using `@modern-js/create` and `modern new` commands was removed
+
+**Handling**:
+
+- **Monorepo Projects**: The Monorepo solution previously provided by Modern.js was based on [pnpm Workspace](https://pnpm.io/workspaces) and did not provide substantial Monorepo management capabilities. It is recommended to directly use community-provided Monorepo solutions such as [Turborepo](https://turbo.build/), [Nx](https://nx.dev/), etc.
+- **Modern.js Module Projects**: It is recommended to use [Rslib](https://rslib.rs/) to create and manage JavaScript library and UI component projects. Rslib is a library development tool based on Rsbuild, providing a simple and intuitive way to create JavaScript libraries. For detailed usage, please refer to the [Rslib official documentation](https://rslib.rs/).
+
+## new and upgrade Commands Removed
+
+Modern.js 3.0 removed the `modern new` and `modern upgrade` commands, and you need to perform operations manually according to the documentation.
+
+**Changes**:
+
+- The `modern new` command is no longer supported in Modern.js 3.0, and you cannot add entries or enable features through commands
+- The `modern upgrade` command is no longer supported in Modern.js 3.0, and you cannot automatically upgrade dependencies through commands
+
+**Handling**:
+
+- **Adding Entries**: You need to manually create entry directories and files according to the documentation. For detailed steps, please refer to the [Page Entries documentation](/guides/concept/entries).
+- **Enabling Features**: You need to manually install dependencies and configure according to the corresponding feature documentation. For example, to enable BFF functionality, you need to install the `@modern-js/plugin-bff` plugin and configure it in `modern.config.ts`.
+- **Upgrading Dependencies**: You need to manually update the versions of all `@modern-js/**` packages in `package.json`, then reinstall dependencies. For detailed steps, please refer to the [Version Upgrade documentation](/guides/get-started/upgrade).
+
+:::info Note
+The purpose of removing these commands is to make the documentation more aligned with the default implementation approach of AI Agents, not encapsulating operations, so that developers can more clearly understand the specific steps of each operation, and it is also convenient for AI Agents to directly execute corresponding operations according to the documentation.
+:::
+
+## ESLint Rule Sets
+
+Modern.js previously provided complete ESLint rule sets, covering @modern-js (Lint rules for Node.js projects) and @modern-js-app (Lint rules for frontend projects). In [v2.60.0](https://github.com/web-infra-dev/modern.js/releases/tag/v2.60.0), we officially removed these rule sets. We encourage developers to choose appropriate code specification tools according to their needs, directly use ESLint combined with community-recommended rules, or use Biome to improve code formatting performance.

package/docs/en/guides/upgrade/overview.mdx

@@ -0,0 +1,33 @@
+# Overview
+
+This guide will help you upgrade from Modern.js 2.0 to Modern.js 3.0.
+
+## Upgrade Overview
+
+Modern.js 3.0 brings significant improvements and changes, including:
+
+- **Build Tool Upgrade**: Default use of [Rspack](https://rspack.dev) for building, no longer supporting Webpack. Build configuration is aligned with [Rsbuild](https://rsbuild.dev).
+- **React Ecosystem Upgrade**: Full support for [React 19](https://react.dev/blog/2024/04/25/react-19) and [React Router v7](https://reactrouter.com).
+- **Plugin System Refactoring**: Redesigned plugin API, supporting custom plugins at CLI, Runtime, and Server layers to extend framework capabilities.
+- **React Server Component**: Support for using React Server Component in [CSR](/guides/get-started/glossary#csr) and [SSR](/guides/basic-features/render/ssr) projects.
+- **Internationalization Enhancement**: Provides out-of-the-box [i18n plugin](/guides/advanced-features/international) to simplify internationalization development workflow.
+- **SSG Capability Improvement**: Provides complete [Static Site Generation (SSG)](/guides/basic-features/render/ssg) support.
+- **Route Configuration Enhancement**: Supports [config-based routing](/guides/basic-features/routes/config-routes), which can be used alone or combined with [convention-based routing](/guides/basic-features/routes/routes), providing more flexible route definition.
+
+## Pre-upgrade Checklist
+
+Before starting the upgrade, please confirm:
+
+1. Your current project is using Modern.js 2.0
+2. The React version is 17 or higher
+3. The Node.js version is 18.20.8 or higher. We recommend using Node.js 22 or higher
+
+## Getting Help
+
+If you encounter any issues during the upgrade process, you can get help through the following channels:
+
+- Check the [Modern.js official documentation](https://modernjs.dev)
+- Search for related issues or submit a new issue in [GitHub Issues](https://github.com/web-infra-dev/modern.js/issues)
+- Join the [Modern.js Discord community](https://discord.gg/modernjs) to communicate with other developers
+
+We recommend providing as much detail as possible when submitting an issue, including error logs, configuration files, and reproduction steps, to help resolve issues faster.