@modern-js/main-doc 2.0.0-beta.6 → 2.0.0-canary.0

package/en/docusaurus-plugin-content-docs/current/guides/basic-features/css/tailwindcss.md

@@ -4,8 +4,6 @@ sidebar_position: 2
 
 # Tailwind CSS
 
-
-
 [Tailwind CSS](https://tailwindcss.com/) is a CSS framework and design system based on Utility Class, which can quickly add common styles to components, and support flexible extension of theme styles. To use [Tailwind CSS](https://tailwindcss.com/) in the Modern.js, just execute `pnpm run new` in the project root directory and turn it on.
 
 Choose as follows:
@@ -23,12 +21,40 @@ import 'tailwindcss/components.css';
 import 'tailwindcss/utilities.css';
 ```
 
-You can then use the Utility Class provided by Tailwind CSS in each component.
+You can then use the Utility Class provided by Tailwind CSS in each component:
+
+```tsx
+const App = () => (
+  <div className="h-12 w-48">
+    <p className="text-xl font-medium text-black">hello world</p>
+  </div>
+);
+```
 
 ::: info Additional
 According to different needs, you can optionally import the CSS files provided by Tailwind CSS. Since the use of `@taiwind` is equivalent to directly importing CSS files, you can refer to the content in the annotate in the [`@tailwind` usage](https://tailwindcss.com/docs/functions-and-directives#tailwind) document for the purpose of the CSS files provided by Tailwind CSS.
 :::
 
+## Tailwind CSS version
+
+Modern.js supports both Tailwind CSS v2 and v3. The framework will recognize the version of `tailwindcss` in the project `package.json` and apply the corresponding configuration. By default, we install Tailwind CSS v3 for you.
+
+If your project is still using Tailwind CSS v2, we recommend that you upgrade to v3 to support JIT and other capabilities. For the differences between Tailwind CSS v2 and v3 versions, please refer to the following articles:
+
+- [Tailwind CSS v3.0](https://tailwindcss.com/blog/tailwindcss-v3)
+- [Upgrade Guide](https://tailwindcss.com/docs/upgrade-guide)
+
+### Browser Compatibility
+
+Both Tailwind CSS v2 and v3 do not support IE 11 browsers. For background, please refer to:
+
+- [Tailwind CSS v3 - Browser Support](https://tailwindcss.com/docs/browser-support).
+- [Tailwind CSS v2 - Browser Support](https://v2.tailwindcss.com/docs/browser-support)
+
+If you use Tailwind CSS on IE 11 browser, some styles may not be available, please pay attention.
+
+## Theme config
+
 When you need to customize the [theme](https://tailwindcss.com/docs/theme) configuration of Tailwind CSS, you can modify it in the configuration [`source.designSystem`](/docs/configure/app/source/design-system), for example, add a color theme `primary`:
 
 ```typescript title="modern.config.ts"
@@ -61,35 +87,4 @@ export default defineConfig({
 });
 ```
 
-## Use the [`Twin`](https://github.com/ben-rogerson/twin.macro)
-
-In the previous chapter, we introduced what CSS-in-JS is and the CSS-in-JS library [styled-components](https://styled-components.com/) commonly used by the community. This section will explain how to use [Tailwind CSS](https://tailwindcss.com/) in CSS with [`Twin`](https://github.com/ben-rogerson/twin.macro). Using [`Twin`](https://github.com/ben-rogerson/twin.macro) makes it easier to use Tailwind CSS in CSS-in-JS code. [`Twin`](https://github.com/ben-rogerson/twin.macro) for its own description is:
-
-> *Twin blends the magic of Tailwind with the flexibility of css-in-js*
-
-After enabling the "Tailwind CSS" function, you first need to install the ['Twin'](https://github.com/ben-rogerson/twin.macro) dependency:
-
-``` bash
-pnpm add twin.macro -D
-```
-
-When the project installs the `twin.macro` dependency, Modern.js detects the dependency and adds twin.macro related configuration to the `baby-plugin-macro` of build-in. So after installing the dependency, there is no need for manual configuration. Here is an example of a simple use of twin.macro:
-
-``` js
-import tw from 'twin.macro'
-
-const Input = tw.input`border hover:border-black`
-```
-
-:::tip
-If a `MacroError: /project/App.tsx` error occurs during runtime, it may be caused by a lack of `twin.macro` dependency.
-:::
-
-For more usage, please refer to the [twin.macro](https://github.com/ben-rogerson/twin.macro/blob/master/docs/index.md).
-
-`twin.macro` reads the `tailwindcss.config.js` files in the project directory by default, or reads the Tailwind CSS configuration via the file path specified by [twin.config](https://github.com/ben-rogerson/twin.macro/blob/master/docs/options.md#options) on the `babel-plugin-macro`. However, these additional configurations are not required in the Modern.js.
-
-When the Tailwind CSS is configured in the `modern.config.ts` file by [`source.designSystem`](/docs/configure/app/source/design-system) and [`tools.tailwindcss`](/docs/configure/app/tools/tailwindcss), these configurations will also take effect on the `twin.macro`.
-
-> When configuring Tailwind CSS for a project, the combination of the two configurations [`source.designSystem`](/docs/configure/app/source/design-system) and [`tools.tailwindcss`](/docs/configure/app/tools/tailwindcss) is equivalent to a separate configuration `tailwindcss.config.js` file.
-> Where [`source.designSystem`](/docs/configure/app/source/design-system) is equivalent to the [`theme`](https://v2.tailwindcss.com/docs/configuration#theme) configuration of Tailwind CSS.
+> When configuring Tailwind CSS for a project, the combination of the two configurations [source.designSystem](/docs/configure/app/source/design-system) and [tools.tailwindcss](/docs/configure/app/tools/tailwindcss) is equivalent to a separate configuration `tailwindcss.config.js` file. Where [source.designSystem](/docs/configure/app/source/design-system) is equivalent to the [theme](https://v2.tailwindcss.com/docs/configuration#theme) configuration of Tailwind CSS.

package/en/docusaurus-plugin-content-docs/current/guides/basic-features/data-fetch.md

@@ -7,6 +7,406 @@ Modern.js provides out of the box fetching data capabilities, developers can use
 
 It should be noted that these APIs do not help applications to initiate requests, but help developers better manage the relationship between data and routing.
 
+## Data loader(recommend)
+
+Modern.js recommends the use of conventional routing for route management. With Modern.js' [conventional (nested) routing](/docs/guides/basic-features/routes#conventional-routing), each routing component (`layout.ts` or `page.ts`) can export a function `loader` that can be executed before the component renders, providing data to the routing component.
+
+:::info
+Modern.js v1 supports getting data by [useLoader](#useloaderold), which is no longer the recommended usage and it is not recommended to mix both except for migration process.
+:::
+
+### Basic example
+
+Each routing component can export a `loader` function and get the  data via the `useLoaderData` function:
+
+```ts
+// routes/user/page.tsx
+import { useLoaderData } from '@modern-js/runtime/router';
+
+export const loader = async(): ProfileData => {
+  const res = await fetch('https://api/user/profile');
+  return await res.json();
+}
+
+export default function UserPage() {
+  const profileData = useLoaderData() as ProfileData;
+  return <div>{profileData}</div>;
+}
+```
+
+In a CSR environment, the `loader` function is executed on the client side, and the browser API can be used within the `loader` function (but it is usually not needed and not recommended).
+
+In an SSR environment, the `loader` function will only be executed on the server side, regardless of the first screen or the navigation on the client side, where any Node.js API can be called, and any dependencies and code used here will not be included in the client bundle.
+
+:::info
+In later versions, Modern.js may support `loader` functions running on the server side as well in CSR environments to improve performance and security, so here it is recommended to keep the loader as pure as possible and only do data fetching scenarios.
+:::
+
+When navigating on the client side, all loader functions under `/user` and `/user/profile` are executed (requested) in parallel based on Modern.js's [conventional routing](/docs/guides/basic-features/routes), i.e. when accessing `/user/profile`, the loader functions under `/user` and `/user/profile` are executed (requested) in parallel to improve client-side performance.
+
+### Loader is defined in a separate file
+
+In addition to supporting the export of `loader` functions from front-end components, Modern.js also supports placing `loader` functions in a separate file, by defining the `loader` function in a separate file, there is no need to pay attention to [side effect](#side-effects) related considerations, but it is important to note that routing components such as `layout.ts` and the loader file `layout.loader.ts` cannot introduce each other's code, if you need the related types you can use `import type`, you can see the following example:
+
+```
+.
+└── routes
+    ├── layout.tsx
+    └── user
+        ├── layout.tsx
+        ├── layout.loader.ts
+        ├── page.tsx
+        └── page.loader.ts
+```
+
+For example, `loader` in [basic example](#basic-example) can be replaced with the following code:
+
+```tsx
+// routes/user/page.loader.tsx
+type ProfileData = { /* some type declarations */ }
+
+export const loader = async(): ProfileData => {
+  const res = await fetch('https://api/user/profile');
+  return await res.json();
+}
+
+// routes/user/page.tsx
+import { useLoaderData } from '@modern-js/runtime/router';
+// here you can only use import type
+import type { ProfileData } from './page.loader';
+
+export default function UserPage() {
+  const profileData = useLoaderData() as ProfileData;
+  return <div>{profileData}</div>;
+}
+```
+
+### `loader` function
+
+The `loader` function has two input parameters：
+
+##### `Params`
+
+When a routing file is passed through `[]`, it is passed as a [dynamic route](/docs/guides/basic-features/routes#dynamic-route) and the dynamic route fragment is passed as an argument to the loader function：
+
+```tsx
+// routes/user/[id]/page.tsx
+import { LoaderArgs } from '@modern-js/runtime/router';
+
+export const loader = async({ params }: LoaderArgs) => {
+  const { id } = params;
+  const res = await fetch(`https://api/user/${id}`);
+  return res.json();
+}
+```
+
+当访问 `/user/123` 时，`loader` 函数的参数为 `{ params: { id: '123' } }`。
+
+#### `request`
+
+`request` is a [Fetch Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) instance.
+
+A common usage scenario is to obtain query parameters via `request`:
+```tsx
+// routes/user/[id]/page.tsx
+import { LoaderArgs } from '@modern-js/runtime/router';
+
+export const loader = async({ request }: LoaderArgs) => {
+  const url = new URL(request.url);
+  const userId = url.searchParams.get("id");
+  return queryUser(userId);
+}
+```
+
+#### Return value
+
+`loader` 函数的返回值可以是任何可序列化的内容，也可以是一个 [Fetch Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) 实例：
+
+```tsx
+export const loader = async(): ProfileData => {
+  return {
+    message: 'hello world',
+  }
+}
+```
+
+By default, the response `Content-type` returned by `loader` is `application/json` and `status` is 200, which you can set by customizing `Response`:
+
+```tsx
+export const loader = async(): ProfileData => {
+  const data = {message: 'hello world'};
+  return new Response(JSON.stringify(data), {
+    status: 200,
+    headers: {
+      "Content-Type": "application/json; utf-8",
+    },
+  });
+}
+```
+
+### Request API
+
+Modern.js does a polyfill of the `fetch` API to initiate requests, which is consistent with the browser's `fetch` API, but can also be used on the server side to initiate requests, meaning that both CSRs and SSRs can use the unified `fetch` API for data fetching：
+
+```tsx
+export async function loader(){
+  const res = await fetch('https://api/user/profile');
+}
+```
+
+### Error handling
+
+In the `loader` function, errors can be handled by `throw error` or `throw response`. When an error is thrown in the `loader` function, Modern.js will stop executing the code in the current loader and switch the front-end UI to the defined [`ErrorBoundary`](/docs/guides/basic-features/routes#errorboundary) component.
+
+```tsx
+// routes/user/profile/page.tsx
+export async function loader(){
+  const res = await fetch('https://api/user/profile');
+  if(!res.ok){
+    throw res;
+  }
+  return res.json();
+}
+
+// routes/user/profile/error.tsx
+import { useRouteError } from '@modern-js/runtime/router';
+const ErrorBoundary = () => {
+  const error = useRouteError() as Response;
+  return (
+    <div>
+      <h1>{error.status}</h1>
+      <h2>{error.statusText}</h2>
+    </div>
+  );
+};
+
+export default ErrorBoundary;
+```
+
+### Get data from upper level components
+
+In many cases, the child component needs to access the data in the ancestor's loader, and you can easily access the ancestor's data with `useRouteLoaderData`: `useRouteLoaderData`:
+
+```tsx
+// routes/user/profile/page.tsx
+import { useRouteLoaderData } from '@modern-js/runtime/router';
+
+export default function UserLayout() {
+  // Get the data returned by the loader in routes/user/layout.tsx
+  const data = useRouteLoaderData('user/layout');
+  return (
+    <div>
+      <h1>{data.name}</h1>
+      <h2>{data.age}</h2>
+    </div>
+  );
+}
+```
+
+`userRouteLoaderData` takes one parameter `routeId`,When using conventional routing, Modern.js will automatically generate `routeId` for you. The value of `routeId` is the path of the corresponding component relative to `src/routes`, as in the example above, the child component wants to get the data returned by the loader in `routes/user/layout.tsx`, the value of `routeId` is  `user/layout`.
+
+In a multi-entry (MPA) scenario, the value of `routeId` needs to be added to the name of the corresponding entry, and the entry name is usually the entry directory name if not specified, such as the following directory structure:
+```bash
+.
+└── src
+    ├── entry1
+    │   ├── layout.tsx
+    └── entry2
+        └── layout.tsx
+```
+
+If you want to get the data returned by the loader in `entry1/layout.tsx`, the value of `routeId` is `entry1_layout`.
+
+### (WIP)Loading UI
+
+:::info
+This feature is currently experimental and the API may be adjusted in the future.
+Currently, only CSR is supported, so stay tuned for Streaming SSR.
+:::
+
+Because fetching data is asynchronous, it is often necessary to display a loading UI before the data fetching is complete, and the following is a basic example, assuming the following directory structure:
+
+```bash
+.
+└── routes
+    ├── layout.tsx
+    └── user
+        ├── layout.tsx
+        └── page.ts
+```
+
+We get the user's detailed data in `user/layout.tsx` and want to show a loading UI before getting the data.
+
+First, add a `loading.tsx` component to the `routes` directory in your project, which will take effect for all routes in the subdirectory (e.g. user):
+```bash
+.
+└── routes
+    ├── layout.tsx
+    ├── loading.tsx
+    └── user
+        ├── layout.tsx
+        └── page.ts
+```
+
+:::info
+For specific usage of the loading component, see [loading](/docs/guides/basic-features/routes#loading)
+:::
+
+Then, add the following code to `user/layout.tsx`:
+
+```tsx title="routes/user/layout.tsx"
+import {
+  Await,
+  defer,
+  useLoaderData,
+  Outlet
+} from '@modern-js/runtime/router';
+
+export const loader = () => {
+  return defer({
+    // fetchUserInfo 是一个异步函数，返回用户信息
+    userInfo: fetchUserInfo(),
+  })
+}
+
+export default function UserLayout() {
+  const { userInfo } = useLoaderData() as {userInfo: Promise<UserInfo>};
+  return (
+    <div>
+      <Await resolve={userInfo} children={userInfo => (
+        <div>
+          <span>{userInfo.name}</span>
+          <span>{userInfo.age}</span>
+          <Outlet>
+        </div>
+      )}>
+      </Await>
+    </div>
+  );
+}
+```
+
+:::info
+For specific usage of the Await component, see [Await](/docs/guides/basic-features/routes#await)
+
+For specific usage of the defer function, see[defer](https://reactrouter.com/en/main/guides/deferred)
+:::
+
+### Side Effects
+
+As mentioned above, Modern.js removes the server-side code `loader` from the client bundle, there are some things you need to be aware of, if you don't want to suffer from side effects, you can define `loader` in a [separate file](#loader-is-defined-in-a-separate-file).
+
+:::info
+In CSR scenarios, the side effects usually have less impact on the project, but you are still expected to follow the following conventions.
+:::
+
+Side effects of a module can be thought of as code that is executed when the module is loaded, such as:
+
+```tsx
+// routes/user/page.tsx
+import { useLoaderData } from '@modern-js/runtime/router';
+// highlight-next-line
+import { transformProfile } from "./utils";
+// highlight-next-line
+console.log(transformProfile);
+
+export const loader = async(): ProfileData => {
+  const res = await fetch('https://api/user/profile');
+  const data = await res.json();
+  return transformProfile(data);
+}
+
+export default function UserPage() {
+  const profileData = useLoaderData() as ProfileData;
+  return <div>{profileData}</div>;
+}
+```
+
+Since `console.log` is executed when `routes/user/page.tsx` is loaded, the compiler does not remove it and `transformProfile` is bundled into the client bundle.
+
+So we do not recommend having any code executed when the module is loaded, including project code and third-party modules used, and the following are some of the ways we do not recommend writing.
+
+```tsx
+// routes/user/page.tsx
+export default function UserPage() {
+  return <div>profile</div>;
+}
+
+UserPage.config = {}
+```
+
+```tsx
+// routes/init.ts
+document.title = 'Modern.js';
+
+// routes/layout.tsx
+import "./init.ts";
+
+export default function Layout() {
+  return <></>
+}
+```
+
+In SSR scenarios, you usually need to use Server Side packages  in the `loader` function, and for non-Node.js core packages, you need to do a re-export using a specially agreed file, such as using `fs-extra`:
+
+```tsx
+// routes/user/avatar.tsx
+import { useLoaderData } from '@modern-js/runtime/router';
+import { readFile } from './utils.server';
+
+type ProfileData = { /* some type declarations */ }
+
+export const loader = async(): ProfileData => {
+  const profile = await readFile('profile.json');
+  return profile;
+}
+
+export default function UserPage() {
+  const profileData = useLoaderData() as ProfileData;
+  return <div>{profileData}</div>;
+}
+
+// routes/user/utils.server.ts
+export * from 'fs-extra';
+```
+
+### Wrong usage
+
+1. Only serializable data can be returned in `loader`. In SSR environments, the return value of the `loader` function is serialized to a JSON string, which is then deserialized to an object on the client side. Therefore, no non-serializable data (such as functions) can be returned in the `loader` function.
+
+:::warning
+This restriction is not currently in place under CSR, but we strongly recommend that you follow it, and we may add it under CSR in the future.
+:::
+
+```ts
+// This won't work!
+export const loader = () => {
+  return {
+    user: {},
+    method: () => {
+
+    }
+  }
+}
+```
+
+2. Modern.js will call the `loader` function for you, you shouldn't call it yourself in the component.
+
+```tsx
+// This won't work!
+export const loader = async () => {
+  const res = fetch('https://api/user/profile');
+  return res.json();
+};
+
+export default function RouteComp() {
+  const data = loader();
+}
+```
+
+3. When run on the server side, the `loader` functions are packaged into a single bundle, so we do not recommend using `__filename` and `__dirname` for server-side code.
+
+
 ## useLoader(Old)
 
 **`useLoader`** is an API in Modern.js old version. The API is a React Hook specially provided for SSR applications, allowing developers to fetch data in components.

package/en/docusaurus-plugin-content-docs/current/guides/basic-features/env-vars.md

@@ -0,0 +1,166 @@
+---
+title: Environment Variable
+sidebar_position: 7
+---
+
+Modern.js provides support for environment variables, including built-in environment variables and custom environment variables.
+
+## Built-in Environment
+
+### NODE_ENV
+
+The current execution environment and is a **read-only** environment variable whose have different values under different execution commands:
+
+- `production`：the default value when exec `modern build` or `modern serve`.
+- `test`：the default value when exec `modern test`.
+- `development`：the default value when exec `modern dev`, alse the default value of other case.
+
+### MODERN_ENV
+
+Set the current execution environment manually. In addition to the values in the NODE_ENV, custom environment names are supported here, such as `staging`, `boe`, etc.
+
+:::tip
+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.
+
+```ts title="App.tsx"
+function App() {
+  if (process.env.MODERN_TARGET === 'browser') {
+    console.log(window.innerHeight);
+  };
+};
+```
+
+In the development environment, you can see that the SSR and CSR bundles as follows:
+
+```js title="dist/bundles/main.js"
+function App() {
+  if (false) {}
+}
+```
+
+```js title="dist/static/main.js"
+function App() {
+  if (true) {
+    console.log(window.innerHeight);
+  }
+}
+```
+
+:::note
+In a production environment, dead code is removed, such as the `if` statement above.
+:::
+
+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.
+
+## Custom Environment Variables
+
+Custom environment variables can be specified in both `shell` and `.env` files.
+
+### Specify via `shell`
+
+Add custom environment variables before the command:
+
+```shell
+REACT_APP_FOO=123 BAR=456 pnpm run dev
+```
+
+### Specify via `.env` file
+
+Create a `.env` file in the project root and add custom environment variables, which are added to the Node.js process by default, for example:
+
+```env
+REACT_APP_FOO=123
+BAR=456
+```
+
+The `.env` file follows the following loading rules:
+
+* `.env`：default.
+* `.env.{ MODERN_ENV | NODE_ENV }`：Setting environment variables for a specific environment overrides the same in `.env`.
+
+When you need to use different config according to the environment, you can define environment variables in the `.env` file corresponding to the environment name, and manually set the execution environment when starting the project.
+
+For example, when starting a project with the following command，the `.env` and `.env.staging` will load:
+
+```shell
+MODERN_ENV=staging pnpm run dev
+```
+
+## Using Environment Variables
+
+### Convention Names
+
+`NODE_ENV` can be used directly in front-end code. In addition, custom environment variables starting with `MODERN_` can also be used directly in code.
+
+For Example:
+
+```js
+if (process.env.NODE_ENV === 'development') {
+  // do something
+}
+```
+
+After executing the `pnpm run dev`, you can see the following bundle:
+
+```js
+if (true) {
+  // do something
+}
+```
+
+In custom HTML templates, you can also use such environment variables directly. For example, in `config/html/head.html`:
+
+```html
+<meta name="test" content="<process.env.NODE_ENV>">
+```
+
+### Any Other Names
+
+If you need to use environment variables with any other names in your code，you can config [`source.globalVars`](/docs/configure/app/source/global-vars), for example:
+
+```typescript title="modern.config.ts"
+export default defineConfig({
+  source: {
+    globalVars: {
+      'process.env.VERSION': process.env.VERSION,
+    }.
+  },
+});
+```
+
+At this point, the `process.env.VERSION` in the code will be replaced with the value of `VERSION` in the environment variables.
+
+:::note
+`source.globalVars` also supports replacing other expressions or strings with specified values, not limited to environment variables.
+:::
+
+## Use Global Replacement
+
+In addition to environment variables, Modern.js also supports replacing variables in code with other values or expressions, which can be used like distinguish development environment and production environment in code.
+
+
+For example, converts the expression `TWO` to `1 + 1`:
+
+```ts
+export default {
+  source: {
+    define: {
+      TWO: '1 + 1',
+    },
+  },
+};
+```
+
+```ts
+const foo = TWO;
+
+// ⬇️ Turn into being...
+const foo = 1 + 1;
+```
+
+In most cases, `source.globalVars` is already sufficient to replace variables. But the values passed in by `source.globalVars` will be serialized by JSON by default. So it cannot be replaced like `1 + 1` in the example above，at this time, we need use [`source.define`](/docs/configure/app/source/define)。