@modern-js/app-tools 3.7.0 → 3.8.0

package/docs/guides/advanced-features/web-server.md

@@ -0,0 +1,288 @@
+# Custom Web Server
+
+Modern.js encapsulates most server-side capabilities required by projects, typically eliminating the need for server-side development. However, in certain scenarios such as user authentication, request preprocessing, or adding page skeletons, custom server-side logic may still be necessary.
+
+To use the Custom Web Server in a Modern.js project, follow these steps:
+
+1. Install `@modern-js/server-runtime` dependency
+
+If the `@modern-js/server-runtime` dependency is not yet installed in your project, install it first:
+
+```bash
+pnpm add @modern-js/server-runtime
+```
+
+:::tip Version Consistency
+Make sure the version of `@modern-js/server-runtime` matches the version of `@modern-js/app-tools` in your project. All Modern.js official packages are released with a uniform version number, and version mismatches may cause compatibility issues.
+
+Check the version of `@modern-js/app-tools` first, then install the same version of `@modern-js/server-runtime`:
+
+```bash
+# Check the current version of @modern-js/app-tools
+pnpm list @modern-js/app-tools
+
+# Install the same version of @modern-js/server-runtime
+pnpm add @modern-js/server-runtime@<version>
+```
+
+:::
+
+2. Create the `server` directory and configuration file
+
+Create a `server/modern.server.ts` file in the project root directory:
+
+```ts title="server/modern.server.ts"
+import { defineServerConfig } from '@modern-js/server-runtime';
+
+export default defineServerConfig({
+  middlewares: [], // Middleware
+  renderMiddlewares: [], // Render Middleware
+  plugins: [], // Plugins
+  onError: () => {}, // Error handling
+});
+```
+
+After creating the file, you can write custom logic in this file.
+
+3. Include `server` directory in `tsconfig.json`
+
+```json5
+{
+  // ...
+  "include": [
+    // ...
+    "server"
+  ]
+}
+```
+
+## Capabilities of the Custom Web Server
+
+Modern.js's Web Server is based on Hono, and in the latest version of the Custom Web Server, we expose Hono's middleware capabilities, you can refer to [Hono API](https://hono.dev/docs/api/context) for more usage.
+
+In the `server/modern.server.ts` file, you can add the following configurations to extend the Server:
+
+- **Middleware**
+- **Render Middleware**
+- **Server-side Plugin**
+
+In the **Plugin**, you can define **Middleware** and **RenderMiddleware**. The middleware loading process is illustrated in the following diagram:
+
+![](https://lf3-static.bytednsdoc.com/obj/eden-cn/10eh7nuhpenuhog/server-md-wf.png)
+### Basic Configuration
+
+```ts title="server/modern.server.ts"
+import { defineServerConfig } from '@modern-js/server-runtime';
+
+export default defineServerConfig({
+  middlewares: [],
+  renderMiddlewares: [],
+  plugins: [],
+  onError: () => {},
+});
+```
+
+### Type Definition
+
+`defineServerConfig` type definition is as follows:
+
+```ts
+import type { MiddlewareHandler } from 'hono';
+
+type MiddlewareOrder = 'pre' | 'post' | 'default';
+type MiddlewareObj = {
+  name: string;
+  path?: string;
+  method?: 'options' | 'get' | 'post' | 'put' | 'delete' | 'patch' | 'all';
+  handler: MiddlewareHandler | MiddlewareHandler[];
+  before?: Array<MiddlewareObj['name']>;
+  order?: MiddlewareOrder;
+};
+type ServerConfig = {
+  middlewares?: MiddlewareObj[];
+  renderMiddlewares?: MiddlewareObj[];
+  plugins?: ServerPlugin[];
+  onError?: (err: Error, c: Context) => Promise<any> | any;
+};
+```
+
+### Middleware
+
+Middleware supports executing custom logic before and after the **request handling** and **page routing** processes in Modern.js services.
+If custom logic needs to handle both API routes and page routes, Middleware is the clear choice.
+
+:::note
+If you only need to handle BFF API routes, you can determine whether a request is for a BFF API by checking if `req.path` starts with the BFF `prefix`.
+:::
+
+Usage is as follows:
+
+```ts title="server/modern.server.ts"
+import {
+  defineServerConfig,
+  type MiddlewareHandler,
+} from '@modern-js/server-runtime';
+
+export const handler: MiddlewareHandler = async (c, next) => {
+  const monitors = c.get('monitors');
+  const start = Date.now();
+
+  await next();
+
+  const end = Date.now();
+  // Report Duration
+  monitors.timing('request_timing', end - start);
+};
+
+export default defineServerConfig({
+  middlewares: [
+    {
+      name: 'request-timing',
+      handler,
+    },
+  ],
+});
+```
+
+:::warning
+You must execute the `next` function to proceed with the subsequent Middleware.
+:::
+
+### RenderMiddleware
+
+If you only need to handle the logic before and after page rendering, modern.js also provides rendering middleware, which can be used as follows:
+
+```ts title="server/modern.server.ts"
+import {
+  defineServerConfig,
+  type MiddlewareHandler,
+} from '@modern-js/server-runtime';
+
+// Inject render performance metrics
+const renderTiming: MiddlewareHandler = async (c, next) => {
+  const start = Date.now();
+
+  await next();
+
+  const end = Date.now();
+  c.res.headers.set('server-timing', `render; dur=${end - start}`);
+};
+
+// Modify the Response Body
+const modifyResBody: MiddlewareHandler = async (c, next) => {
+  await next();
+
+  const { res } = c;
+  const text = await res.text();
+  const newText = text.replace('<body>', '<body> <h3>bytedance</h3>');
+
+  c.res = c.body(newText, {
+    status: res.status,
+    headers: res.headers,
+  });
+};
+
+export default defineServerConfig({
+  renderMiddlewares: [
+    {
+      name: 'render-timing',
+      handler: renderTiming,
+    },
+    {
+      name: 'modify-res-body',
+      handler: modifyResBody,
+    },
+  ],
+});
+```
+
+### Plugin
+
+Modern.js supports adding the aforementioned middleware and rendering middleware for the Server in custom plugins, which can be used as follows:
+
+```ts title="server/plugins/server.ts"
+import type { ServerPlugin } from '@modern-js/server-runtime';
+
+export default (): ServerPlugin => ({
+  name: 'serverPlugin',
+  setup(api) {
+    api.onPrepare(() => {
+      const { middlewares, renderMiddlewares } = api.getServerContext();
+
+      // Inject server-side data for page dataLoader consumption
+      middlewares?.push({
+        name: 'server-plugin-middleware',
+        handler: async (c, next) => {
+          c.set('message', 'hi modern.js');
+          await next();
+          // ...
+        },
+      });
+
+      // redirect
+      renderMiddlewares?.push({
+        name: 'server-plugin-render-middleware',
+        handler: async (c, next) => {
+          const user = getUser(c.req);
+          if (!user) {
+            return c.redirect('/login');
+          }
+
+          await next();
+        },
+      });
+    });
+  },
+});
+```
+
+```ts title="server/modern.server.ts"
+import { defineServerConfig } from '@modern-js/server-runtime';
+import serverPlugin from './plugins/serverPlugin';
+
+export default defineServerConfig({
+  plugins: [serverPlugin()],
+});
+```
+
+```ts title="src/routes/page.data.ts"
+import { useHonoContext } from '@modern-js/server-runtime';
+import { defer } from '@modern-js/runtime/router';
+
+export default () => {
+  const ctx = useHonoContext();
+  // SSR scenario consumes data injected by the Server Side
+  const message = ctx.get('message');
+
+  // ...
+};
+```
+
+### onError
+
+`onError` is a global error handling function used to capture and handle all uncaught errors in the Modern.js server. By customizing the `onError` function, developers can uniformly handle different types of errors, return custom error responses, and implement features such as error logging and error classification.
+
+Below is a basic example of an `onError` configuration:
+
+```ts title="server/modern.server.ts"
+import { defineServerConfig } from '@modern-js/server-runtime';
+
+export default defineServerConfig({
+  onError: (err, c) => {
+    // Log the error
+    console.error('Server error:', err);
+
+    // Return different responses based on the error type
+    if (err instanceof SyntaxError) {
+      return c.json({ error: 'Invalid JSON' }, 400);
+    }
+
+    // Customize BFF error response based on request path
+    if (c.req.path.includes('/api')) {
+      return c.json({ message: 'API error occurred' }, 500);
+    }
+
+    return c.text('Internal Server Error', 500);
+  },
+});
+```

package/docs/guides/basic-features/alias.md

@@ -0,0 +1,102 @@
+# Path Alias
+
+Path aliases allow developers to define aliases for modules, making it easier to reference them in code. This can be useful when you want to use a short, easy-to-remember name for a module instead of a long, complex path.
+
+For example, if you frequently reference the `src/common/request.ts` module in your project, you can define an alias for it as `@request` and then use `import request from '@request'` in your code instead of writing the full relative path every time. This also allows you to move the module to a different location without needing to update all the import statements in your code.
+
+In Modern.js, there are two ways to set up path aliases:
+
+- Through the `paths` configuration in `tsconfig.json`.
+- Through the [source.alias](/configure/app/source/alias.md) configuration.
+
+## Using `tsconfig.json`'s `paths` Configuration
+
+You can configure aliases through the `paths` configuration in `tsconfig.json`, which is the recommended approach in TypeScript projects as it also resolves the TS type issues related to path aliases.
+
+For example:
+
+```json title="tsconfig.json"
+{
+  "compilerOptions": {
+    "paths": {
+      "@common/*": ["./src/common/*"]
+    }
+  }
+}
+```
+
+After configuring, if you reference `@common/Foo.tsx` in your code, it will be mapped to the `<project>/src/common/Foo.tsx` path.
+
+:::tip
+You can refer to the [TypeScript - paths](https://www.typescriptlang.org/tsconfig#paths) documentation for more details.
+:::
+
+## Use `source.alias` Configuration
+
+Modern.js provides the [source.alias](/configure/app/source/alias.md) configuration option. You can configure this option using an object or a function.
+
+### Use Cases
+
+Since the `paths` configuration in `tsconfig.json` is written in a static JSON file, it lacks dynamism.
+
+The `source.alias` configuration can address this limitation by allowing you to dynamically set the `source.alias` using JavaScript code, such as based on environment variables.
+
+### Object Usage
+
+You can configure `source.alias` using an object, where the relative paths will be automatically resolved to absolute paths.
+
+For example:
+
+```js
+export default {
+  source: {
+    alias: {
+      '@common': './src/common',
+    },
+  },
+};
+```
+
+After configuring, if you reference `@common/Foo.tsx` in your code, it will be mapped to the `<project>/src/common/Foo.tsx` path.
+
+### Function Usage
+
+You can also configure `source.alias` as a function, which receives the built-in `alias` object and allows you to modify it.
+
+For example:
+
+```js
+export default {
+  source: {
+    alias: alias => {
+      alias['@common'] = './src/common';
+      return alias;
+    },
+  },
+};
+```
+
+### Priority
+
+The `paths` configuration in `tsconfig.json` takes precedence over the `source.alias` configuration. When a path matches the rules defined in both `paths` and `source.alias`, the value defined in `paths` will be used.
+
+You can adjust the priority of these two options using [source.aliasStrategy](/configure/app/source/alias-strategy.md).
+
+## Default Aliases
+
+The Modern.js framework comes with the following aliases built-in:
+
+```json
+{
+  "@": "./src",
+  "@shared": "./shared"
+}
+```
+
+Additionally, when the BFF plugin of the framework is enabled, the `@api` alias is automatically added.
+
+```json
+{
+  "@api": "./api"
+}
+```

package/docs/guides/basic-features/css/css-in-js.md

@@ -0,0 +1,72 @@
+# Using CSS-in-JS
+
+CSS-in-JS is a technique that allows you to write CSS styles within JS files.
+
+Modern.js supports the commonly used community CSS-in-JS library [styled-components](https://styled-components.com/), which uses JavaScript's new feature [Tagged template](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#tagged_templates) to write component CSS styles.
+
+The Modern.js plugin `@modern-js/plugin-styled-components` provides support for styled-components and adds server-side rendering capability for styled-components. You can use styled-components by installing the `@modern-js/plugin-styled-components` plugin.
+
+## Using styled-components in Modern.js
+
+First, you need to install the `styled-components` plugin dependency and the `styled-components` library:
+
+
+```sh [npm]
+npm install @modern-js/plugin-styled-components styled-components -D
+```
+
+```sh [yarn]
+yarn add @modern-js/plugin-styled-components styled-components -D
+```
+
+```sh [pnpm]
+pnpm install @modern-js/plugin-styled-components styled-components -D
+```
+
+Then configure the `styled-components` plugin in `modern.config.ts`:
+
+```ts
+import { defineConfig } from '@modern-js/app-tools';
+import { styledComponentsPlugin } from '@modern-js/plugin-styled-components';
+
+export default defineConfig({
+  plugins: [
+    styledComponentsPlugin({
+      // ...
+      displayName: true,
+      minify: process.env.NODE_ENV === 'production',
+    }),
+  ],
+});
+```
+
+The configuration options of the styledComponentsPlugin plugin are the same as those of the [@rsbuild/plugin-styled-components](https://www.npmjs.com/package/@rsbuild/plugin-styled-components) plugin. You can refer to the documentation of [@rsbuild/plugin-styled-components](https://www.npmjs.com/package/@rsbuild/plugin-styled-components) for configuration.
+
+## Writing styles with styled-components
+
+When you need to write a `div` component with red text inside, you can implement it as follows:
+
+```js
+import styled from '@modern-js/plugin-styled-components/styled';
+
+const RedDiv = styled.div`
+  color: red;
+`;
+```
+
+When you need to dynamically set component styles based on the component's `props`, for example, when the `primary` attribute of `props` is `true`, the button's color is white, otherwise red, the implementation is as follows:
+
+```js
+import styled from '@modern-js/plugin-styled-components/styled';
+
+const Button = styled.button`
+  color: ${props => (props.primary ? 'white' : 'red')};
+  font-size: 1em;
+`;
+```
+
+For more usage of styled-components, please refer to the [styled-components official website](https://styled-components.com/).
+
+:::tip Tip
+If you want to use other CSS-in-JS libraries such as [styled-jsx](https://www.npmjs.com/package/styled-jsx), [Emotion](https://emotion.sh/), etc., you need to install the corresponding dependencies first. Please refer to the official websites of the respective libraries for specific usage.
+:::

package/docs/guides/basic-features/css/css-modules.md

@@ -0,0 +1,212 @@
+# Use CSS Modules
+
+[CSS Modules](https://github.com/css-modules/css-modules) allows us to write CSS code in a modular way, and these styles can be imported and used in JavaScript files. Using CSS Modules can automatically generate unique class names, isolate styles between different modules, and avoid class name conflicts.
+
+Modern.js supports CSS Modules by default, you don't need to add additional configuration. Our convention is to use the `[name].module.css` filename to enable CSS Modules.
+
+The following style files are considered CSS Modules:
+
+- `*.module.scss`
+- `*.module.less`
+- `*.module.css`
+
+## Example
+
+- Write style:
+
+```css
+/* button.module.css */
+.error {
+  background: red;
+}
+```
+
+- Using styles:
+
+```tsx
+// Button.tsx
+import React, { Component } from 'react';
+// import style file
+import styles from './button.module.css';
+
+export default () => {
+  return <button className={styles.error}>Error Button</button>;
+};
+```
+
+## Enable CSS Modules for all CSS files
+
+By default, only files ending in `*.module.css` are treated CSS Modules.
+
+If you want to treat all CSS files in the source directory as CSS Modules, you can enable the [output.disableCssModuleExtension](/configure/app/output/disable-css-module-extension.md) config, for example:
+
+```ts
+export default {
+  output: {
+    disableCssModuleExtension: true,
+  },
+};
+```
+
+When set, the following two files are treated as CSS Modules:
+
+```ts
+import styles1 from './foo.module.css';
+import styles2 from './bar.css';
+```
+
+:::tip
+We do not recommend enabling this config, because after enabling disableCssModuleExtension, CSS Modules files and ordinary CSS files cannot be clearly distinguished, which is not conducive to long-term maintenance.
+:::
+
+## Enable CSS Modules for the specified style file
+
+By default, only files ending in `*.module.css` are treated CSS Modules.
+
+If you want to enable CSS Modules only for specified style files, you can configure [output.cssModules](/configure/app/output/css-modules.md), for example:
+
+```ts
+export default {
+  output: {
+    cssModules: {
+      auto: resource => {
+        return resource.includes('.module.') || resource.includes('shared/');
+      },
+    },
+  },
+};
+```
+
+## Add Type Declaration
+
+When you import CSS Modules in TypeScript code, TypeScript may prompt that the module is missing a type definition:
+
+```
+TS2307: Cannot find module './index.module.css' or its corresponding type declarations.
+```
+
+To fix this, you need to add a type declaration file for the CSS Modules, please create a `src/global.d.ts` file, and add the corresponding type declaration:
+
+```ts title="src/global.d.ts"
+declare module '*.module.css' {
+  const classes: { readonly [key: string]: string };
+  export default classes;
+}
+
+declare module '*.module.scss' {
+  const classes: { readonly [key: string]: string };
+  export default classes;
+}
+
+declare module '*.module.sass' {
+  const classes: { readonly [key: string]: string };
+  export default classes;
+}
+
+declare module '*.module.less' {
+  const classes: { readonly [key: string]: string };
+  export default classes;
+}
+
+declare module '*.module.styl' {
+  const classes: { readonly [key: string]: string };
+  export default classes;
+}
+```
+
+If you enabled the `disableCssModuleExtension` config, you also need to add the following types:
+
+```ts title="src/global.d.ts"
+declare module '*.css' {
+  const classes: { readonly [key: string]: string };
+  export default classes;
+}
+
+declare module '*.scss' {
+  const classes: { readonly [key: string]: string };
+  export default classes;
+}
+
+declare module '*.sass' {
+  const classes: { readonly [key: string]: string };
+  export default classes;
+}
+
+declare module '*.less' {
+  const classes: { readonly [key: string]: string };
+  export default classes;
+}
+
+declare module '*.styl' {
+  const classes: { readonly [key: string]: string };
+  export default classes;
+}
+```
+
+After adding the type declaration, if the type error still exists, you can try to restart the current IDE, or adjust the directory where `global.d.ts` is located, making sure the TypeScript can correctly identify the type definition.
+
+## Generate exact type definitions
+
+Although the above method can provide the type of CSS Modules, it cannot accurately prompt which classNames are exported by a certain CSS file.
+
+Modern.js supports generating accurate type declarations for CSS Modules, you only need to enable the [output.enableCssModuleTSDeclaration](/configure/app/output/enable-css-module-tsdeclaration.md) config, and then execute the build, Modern.js will generate type declaration files for all CSS Modules.
+
+```ts
+export default {
+  output: {
+    enableCssModuleTSDeclaration: true,
+  },
+};
+```
+
+### Example
+
+For example, there are two files `src/index.ts` and `src/index.module.scss` under a certain folder:
+
+```tsx title="src/index.ts"
+import styles from './index.module.scss';
+
+export default () => {
+  return (
+    <div>
+      <div className={styles.pageHeader}>Page Header</div>
+    </div>
+  );
+};
+```
+
+```scss title="src/index.module.scss"
+.page-header {
+  color: black;
+}
+```
+
+After executing the build, the `src/index.module.scss.d.ts` type declaration file will be automatically generated:
+
+```ts title="src/index.module.scss.d.ts"
+// This file is automatically generated.
+// Please do not change this file!
+interface CssExports {
+  'page-header': string;
+  pageHeader: string;
+}
+export const cssExports: CssExports;
+export default cssExports;
+```
+
+Then open the `src/index.ts` file again, you will see that the `styles` object already has a exact type.
+
+### Related configuration
+
+In the above example, `src/index.module.scss.d.ts` is generated by compilation, you can choose to commit them to the Git repository, or you can choose to ignore them in the `.gitignore` file:
+
+```bash
+# Ignore auto generated CSS declarations
+*.module.css.d.ts
+*.module.sass.d.ts
+*.module.scss.d.ts
+*.module.less.d.ts
+*.module.styl.d.ts
+```
+
+In addition, if the generated code causes ESLint to report errors, you can also add the above configuration to the `.eslintignore` file.

package/docs/guides/basic-features/css/css.md

@@ -0,0 +1,27 @@
+# Styling
+
+Modern.js has built-in a variety of commonly used CSS solutions, including Less / Sass / Stylus preprocessors, PostCSS, CSS Modules, CSS-in-JS, and Tailwind CSS.
+
+## Using Less, Sass and Stylus
+
+Modern.js has built-in popular community CSS preprocessors, including Less and Sass.
+
+By default, you don't need to configure Less and Sass. If you have custom loader configuration requirements, you can set them up by configuring [tools.less](/configure/app/tools/less.md) and [tools.sass](/configure/app/tools/sass.md).
+
+You can also use Stylus in Modern.js by installing the Stylus plugin provided by Rsbuild. For usage, please refer to [Stylus Plugin](https://v2.rsbuild.rs/plugins/list/plugin-stylus).
+
+## Using PostCSS
+
+Modern.js has built-in [PostCSS](https://postcss.org/) to transform CSS code.
+
+Please refer to [Rsbuild - Using PostCSS](https://v2.rsbuild.rs/guide/styling/css-usage) for detailed usage.
+
+## Using Lightning CSS
+
+Modern.js supports using [Lightning CSS](https://lightningcss.dev/) to convert CSS code. This feature can be turned on by configuring [tools.lightningcssLoader](/configure/app/tools/lightningcss-loader.md).
+
+Please refer to [Rsbuild - Using Lightning CSS](https://v2.rsbuild.rs/guide/styling/css-usage#lightning-css) for detailed usage.
+
+## Using Uno CSS
+
+Please read the [Rsbuild - Using UnoCSS](https://v2.rsbuild.rs/guide/styling/unocss) for detailed usage.