@modern-js/main-doc 2.14.0 → 2.16.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @modern-js/main-doc
 
+## 2.16.0
+
+### Patch Changes
+
+- 63b3538: fix: dev server crashed when prepare api handler failed
+
+  fix: 修复更新 api server 报错导致 dev server 退出的问题
+
+- fe92de6: fix(builder): browserslist config should not affect node bundles
+
+  fix(builder): 修复 browserslist 配置会对 node 产物生效的问题
+
+- 4e876ab: chore: package.json include the monorepo-relative directory
+
+  chore: 在 package.json 中声明 monorepo 的子路径
+
+- Updated dependencies [fe92de6]
+- Updated dependencies [4e876ab]
+  - @modern-js/builder-doc@2.16.0
+
+## 2.15.0
+
+### Patch Changes
+
+- @modern-js/builder-doc@2.15.0
+
 ## 2.14.0
 
 ### Patch Changes

package/docs/en/about/contributing-guide.mdx

@@ -0,0 +1,268 @@
+---
+sidebar_position: 3
+---
+
+# Contributing Guide
+
+Thanks for that you are interested in contributing to Modern.js. Before starting your contribution, please take a moment to read the following guidelines.
+
+---
+
+## Setup the Dev Environment
+
+### Fork the Repo
+
+[Fork](https://help.github.com/articles/fork-a-repo/) this repository to your
+own GitHub account and then [clone](https://help.github.com/articles/cloning-a-repository/) it to your local.
+
+### Install Node.js
+
+We recommend using Node.js 16 or 18. You can check your currently used Node.js version with the following command:
+
+```bash
+node -v
+#v16.18.0
+```
+
+If you do not have Node.js installed in your current environment, you can use [nvm](https://github.com/nvm-sh/nvm) or [fnm](https://github.com/Schniz/fnm) to install it.
+
+Here is an example of how to install the Node.js 16 LTS version via nvm:
+
+```bash
+# Install the LTS version of Node.js 16
+nvm install 16 --lts
+
+# Make the newly installed Node.js 16 as the default version
+nvm alias default 16
+
+# Switch to the newly installed Node.js 16
+nvm use 16
+```
+
+### Install pnpm
+
+```sh
+# Enable pnpm with corepack, only available on Node.js >= `v14.19.0`
+corepack enable
+```
+
+### Install Dependencies
+
+```sh
+pnpm install
+```
+
+What this will do:
+
+- Install all dependencies
+- Create symlinks between packages in the monorepo
+- Run the `prepare` script to build all packages (this will take some time, but is necessary to make ensure all packages are built)
+
+> A full rebuild of all packages is generally not required after this. If a new feature you are developing requires an updated version of another package, it is usually sufficient to build the changed dependencies.
+
+### Set Git Email
+
+Please make sure you have your email set up in `<https://github.com/settings/emails>`. This will be needed later when you want to submit a pull request.
+
+Check that your git client is already configured the email:
+
+```sh
+git config --list | grep email
+```
+
+Set the email to global config:
+
+```sh
+git config --global user.email "SOME_EMAIL@example.com"
+```
+
+Set the email for local repo:
+
+```sh
+git config user.email "SOME_EMAIL@example.com"
+```
+
+---
+
+## Making Changes and Building
+
+Once you have set up the local development environment in your forked repo, we can start development.
+
+### Checkout A New Branch
+
+It is recommended to develop on a new branch, as it will make things easier later when you submit a pull request:
+
+```sh
+git checkout -b MY_BRANCH_NAME
+```
+
+### Build the Package
+
+To build the package you want to change, first open the package directory, then run the `build` command:
+
+```sh
+# Replace some-path with the path of the package you want to work on
+cd ./packages/some-path
+pnpm run build
+```
+
+Alternatively, you can build the package from the root directory of the repository using the `--filter` option:
+
+```sh
+pnpm run --filter @modern-js/some-package build
+```
+
+Build all packages:
+
+```sh
+pnpm run prepare
+```
+
+If you need to clean all `node_modules/*` in the project, run the `reset` command:
+
+```sh
+pnpm run reset
+```
+
+---
+
+## Testing
+
+### Add New Tests
+
+If you've fixed a bug or added code that should be tested, then add some tests.
+
+You can add unit test cases in the `<PACKAGE_DIR>/tests` folder. The test syntax is based on [Jest](https://jestjs.io/) and [Vitest](https://vitest.dev/).
+
+### Run Unit Tests
+
+Before submitting a pull request, it's important to make sure that the changes haven't introduced any regressions or bugs. You can run the unit tests for the project by executing the following command:
+
+```sh
+pnpm run test
+```
+
+Alternatively, you can run the unit tests of single package using the `--filter` option:
+
+```sh
+pnpm run --filter @modern-js/some-package test
+```
+
+### Run E2E Tests
+
+In addition to the unit tests, the Modern.js also includes end-to-end (E2E) tests, which checks the functionality of the application as a whole.
+
+You can run the `test:e2e` command to run the E2E tests:
+
+```sh
+pnpm run test:e2e
+```
+
+If you need to run a specified test, you can add keywords to filter:
+
+```sh
+# Only run test cases with the copy-assets keyword
+npx jest copy-assets
+```
+
+---
+
+## Linting
+
+To help maintain consistency and readability of the codebase, we use a ESLint to lint the codes.
+
+You can run the Linter by executing the following command:
+
+```sh
+pnpm run lint
+```
+
+---
+
+## Documentation
+
+Currently Modern.js provides documentation in English and Chinese. If you can use Chinese, please update both documents at the same time. Otherwise, just update the English documentation.
+
+You can find all the documentation in the `packages/document` folder:
+
+```bash
+root
+└─ packages
+   └─ document
+       ├─ builder-doc    # Documentation for Modern.js Builder
+       ├─ doc-tools-doc  # Documentation for Modern.js Doc
+       ├─ main-doc       # Documentation for Modern.js Framework
+       └─ module-doc     # Documentation for Modern.js Module
+```
+
+This website is built with [Modern.js Doc](https://modernjs.dev/doc-tools), the document content can be written using markdown or mdx syntax. You can refer to the [Modern.js Doc Website](https://modernjs.dev/doc-tools) for detailed usage.
+
+The source code of Modern.js Doc can be found in [this folder](https://github.com/web-infra-dev/modern.js/tree/main/packages/solutions/doc-tools).
+
+---
+
+## Submitting Changes
+
+### Add a Changeset
+
+Modern.js is using [Changesets](https://github.com/changesets/changesets) to manage the versioning and changelogs.
+
+If you've changed some packages, you need add a new changeset for the changes. Please run `change` command to select the changed packages and add the changeset info.
+
+```sh
+pnpm run change
+```
+
+### Committing your Changes
+
+Commit your changes to your forked repo, and [create a pull request](https://help.github.com/articles/creating-a-pull-request/).
+
+### Format of PR titles
+
+The format of PR titles follow Conventional Commits.
+
+An example:
+
+```
+feat(plugin-swc): Add `xxx` config
+^    ^    ^
+|    |    |__ Subject
+|    |_______ Scope
+|____________ Type
+```
+
+---
+
+## Publishing
+
+We use **Modern.js Monorepo Solution** to manage version and changelog.
+
+Repository maintainers can publish a new version of all packages to npm.
+
+Here are the steps to publish (we generally use CI for releases and avoid publishing npm packages locally):
+
+1. Pull latest code from the `main` branch.
+2. Install:
+
+```sh
+pnpm i
+```
+
+3. Build packages:
+
+```sh
+pnpm run prepare
+```
+
+4. Bump version:
+
+```sh
+pnpm run bump
+```
+
+5. Commit the version change.
+
+```sh
+git add .
+git commit -m "Release va.b.c"
+```

package/docs/en/about/releases.mdx

@@ -0,0 +1,31 @@
+---
+sidebar_position: 2
+---
+
+# Releases
+
+## Changelog
+
+Please visit [GitHub - Releases](https://github.com/web-infra-dev/modern.js/releases) to see what has changed with each release of Modern.js.
+
+## Version Specification
+
+Modern.js follows the [Semantic Versioning](https://semver.org) specification.
+
+- Major version: Contains incompatible API changes.
+- Minor version: Contains backward compatible functional changes.
+- Patch version: Contains backwards compatible bug fixes
+
+## Release Cycle
+
+- Modern.js generally releases an official release every Thursday.
+- If critical bugs appear, we will release a revised version on the same day.
+- We expect to keep Modern.js v2 stable and compatible, there are currently no plans to release the next major version.
+
+## Version Upgrade
+
+When you need to upgrade the Modern.js version in your project, you can use the `modern upgrade` command, refer to [Upgrade](/guides/get-started/upgrade).
+
+```bash
+npx modern upgrade
+```

package/docs/en/about/showcase.mdx

@@ -0,0 +1,15 @@
+---
+sidebar_position: 0
+---
+
+# Showcase
+
+Welcome to the Modern.js showcase page! Here, we present a collection of websites that have been built using Modern.js.
+
+If you have built a website using Modern.js, we would love for you to share it with the community. Simply reply to the GitHub discussion thread with a link to your website. We will collect content on a regular basis and display it on the current page.
+
+## The Cases
+
+import { ShowcaseList } from '@site/src/components/ShowcaseList';
+
+<ShowcaseList />

package/docs/en/about/team.mdx

@@ -0,0 +1,29 @@
+---
+sidebar_position: 1
+---
+
+# Meet the Team
+
+The development of Modern.js is driven by ByteDance's Modern.js team and community contributors.
+
+## Core Team Members
+
+The Modern.js core team members:
+
+import { RandomMemberList } from '@site/src/components/RandomMemberList';
+
+<RandomMemberList />
+
+## All Contributors
+
+Thanks to the following friends for their contributions to Modern.js:
+
+<a
+  href="https://github.com/web-infra-dev/modern.js/graphs/contributors"
+  style={{ display: 'block', marginTop: 24 }}
+>
+  <img
+    src="https://opencollective.com/modernjs/contributors.svg?width=890&button=false"
+    alt="contributors"
+  />
+</a>

package/docs/en/configure/app/output/disable-svgr.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_label: disableSvgr
+---
+
+# output.disableSvgr
+
+:::tip
+This config is provided by Modern.js Builder, more detail can see [output.disableSvgr](https://modernjs.dev/builder/en/api/config-output.html#outputdisablesvgr).
+:::
+
+import Main from '@modern-js/builder-doc/docs/en/config/output/disableSvgr.md';
+
+<Main />

package/docs/en/guides/basic-features/env-vars.mdx

@@ -31,7 +31,9 @@ MODERN_ENV priority is higher than NODE_ENV.
 
 ### MODERN_TARGET
 
-Auto inject when use `@modern-js/runtime`, Used to distinguish between SSR and CSR environments. Developers can judge by themselves in the code, and dead code will be removed by default when building.
+When using `@modern-js/runtime`, Modern.js will automatically inject `MODERN_TARGET` to distinguish between SSR and CSR environments.
+
+You can use `process.env.MODERN_TARGET` to judge the environment and execute the appropriate code.
 
 ```ts title="App.tsx"
 function App() {
@@ -41,9 +43,10 @@ function App() {
 }
 ```
 
-In the development environment, you can see that the SSR and CSR bundles as follows:
+After the development build, you can see that the SSR and CSR bundles as follows:
 
 ```js title="dist/bundles/main.js"
+// SSR bundles
 function App() {
   if (false) {
   }
@@ -51,6 +54,7 @@ function App() {
 ```
 
 ```js title="dist/static/main.js"
+// CSR bundles
 function App() {
   if (true) {
     console.log(window.innerHeight);
@@ -58,12 +62,16 @@ function App() {
 }
 ```
 
-:::note
-In a production environment, dead code is removed, such as the `if` statement above.
+This can provide different outputs for different environments to ensure that the bundle size is minimized. It can also be convenient to deal with some side effects for different environments.
 
-:::
+:::note Dead Code Elimination
+In the production environment, minimizers such as Terser and SWC will analyze the code and remove dead code to reduce the bundle size. This process is called "Dead Code Elimination" (DCE).
 
-This can provide different products for different client sides to ensure that the bundle size is minimized. It can also be convenient to deal with some side effects in the code in different environments.
+For example, the code inside the `if (false)` statement will be removed, while the code inside the `if (true)` will be preserved.
+
+If you do not use `process.env.MODERN_TARGET` as described above, the code minimizer may not be able to analyze the dead code, resulting in an increased bundle size.
+
+:::
 
 ## Custom Environment Variables
 

package/docs/en/guides/troubleshooting/dependencies.mdx

@@ -0,0 +1,110 @@
+---
+sidebar_position: 1
+---
+
+# Dependencies FAQ
+
+### How to check the actual installed version of a dependency in the project?
+
+You can use the `ls` command that provided by the package manager to view the dependencies version.
+
+The following are some basic examples, please refer to the documentation of each package manager for detailed usage.
+
+**npm / yarn**
+
+For projects using npm or yarn, the `npm ls` command can be used.
+
+For example, execute `npm ls @modern-js/core`, you can see the following results:
+
+```
+project
+└─┬ @modern-js/app-tools@2.0.0
+  └── @modern-js/core@2.0.0
+```
+
+**pnpm**
+
+For projects using pnpm, you can use `pnpm ls` command.
+
+For example, execute `pnpm ls @modern-js/core --depth Infinity`, you can see the following results:
+
+```
+devDependencies:
+@modern-js/app-tools 2.0.0
+└── @modern-js/core 2.0.0
+```
+
+---
+
+### The engine "node" is incompatible when installing dependencies?
+
+If the following error message appears when installing dependencies, it means that the version of Node.js used in the current environment is too low, and Node.js needs to be upgraded to a higher version.
+
+```bash
+The engine "node" is incompatible with this module.
+
+Expected version ">=14.17.6". Got "12.20.1"
+```
+
+When using Modern.js, it is recommended to use [Node.js 14.x](https://nodejs.org/download/release/latest-v14.x/) or [Node.js 16.x](https://nodejs.org/download/release/latest-v16.x/).
+
+If the Node.js version in the current environment is lower than the required version, you can use [nvm](https://github.com/nvm-sh/nvm) or [fnm](https://github.com/Schniz /fnm) and other tools for version switching.
+
+Here's an example using nvm:
+
+```
+# Install Node.js v14
+nvm install 14
+
+# Switch to Node 14
+nvm use 14
+
+# Set Node 14 as the default version
+nvm default 14
+```
+
+It is recommended to use [fnm](https://github.com/Schniz/fnm) in the local development environment. Its usage is similar to nvm, but it has better performance than nvm.
+
+---
+
+### ReactNode type error after upgrading dependencies?
+
+If the following types of errors are reported after upgrading the project's dependencies, it means that the wrong `@types/react` version is installed in the project.
+
+```bash
+The types returned by 'render()' are incompatible between these types.
+Type 'React.ReactNode' is not assignable to type 'import("/node_modules/@types/react/index").ReactNode'.
+Type '{}' is not assignable to type 'ReactNode'.
+```
+
+The reason for this problem is that the ReactNode type definitions in React 18 and React 16/17 are different. If there are multiple different `@types/react` versions in the project, there will be a ReactNode type conflict, resulting in the above error.
+
+The solution is to lock `@types/react` and `@types/react-dom` in the project to a unified version, such as `v17`.
+
+```json
+{
+  "@types/react": "^17",
+  "@types/react-dom": "^17"
+}
+```
+
+For the method of locking the dependency version, please refer to [Lock nested dependency](/guides/get-started/upgrade.html#lock-nested-dependency).
+
+---
+
+### After pnpm install, there are some peer dependencies warnings in the console?
+
+The reason for this warning is that the version range of peer dependencies declared by some third-party npm packages does not match the version range installed in Modern.js.
+
+In most cases, you can ignore the peer dependency warnings because it will not affect the use of Modern.js.
+
+---
+
+### What is the minimum React version supported by the Modern.js framework?
+
+The recommended React version for **Modern.js framework is >= 18.0.0**, and different features have different React version requirements.
+
+- If you are using React 17, some framework features, such as Steaming SSR, will not be available as they rely on new features provided by React 18.
+- If you're still using React 16, you won't be able to use Modern.js's runtime or server-side featurs. You can consider using Modern.js's build mode, that is, only use Modern.js as a builder. In this case, you can still use React 16.
+
+In a future major release of Modern.js, we will remove support for React 16 and React 17. Please upgrade to React 18+ as soon as possible.