@bleedingdev/modern-js-app-tools 3.5.0-ultramodern.98 → 3.5.0-ultramodern.99

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

@@ -0,0 +1,296 @@
+---
+sidebar_position: 16
+---
+
+# 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:
+
+<img
+  src="https://lf3-static.bytednsdoc.com/obj/eden-cn/10eh7nuhpenuhog/server-md-wf.png"
+  style={{ width: '100%', maxWidth: '540px' }}
+/>
+
+### 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/_meta.json

@@ -0,0 +1,49 @@
+[
+  {
+    "type": "dir",
+    "name": "routes",
+    "label": "Routes",
+    "collapsed": true
+  },
+  {
+    "type": "dir",
+    "name": "data",
+    "label": "data-solution",
+    "collapsed": true
+  },
+  {
+    "type": "dir",
+    "name": "render",
+    "label": "rendering",
+    "collapsed": true
+  },
+  {
+    "type": "dir",
+    "name": "css",
+    "label": "css-solution",
+    "collapsed": true
+  },
+  "html",
+  {
+    "type": "dir",
+    "name": "static-assets",
+    "label": "static-assets",
+    "collapsed": true
+  },
+  {
+    "type": "dir",
+    "name": "debug",
+    "label": "debug",
+    "collapsed": true
+  },
+  {
+    "type": "dir",
+    "name": "testing",
+    "label": "testing",
+    "collapsed": true
+  },
+  "alias",
+  "env-vars",
+  "output-files",
+  "deploy"
+]

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

@@ -0,0 +1,106 @@
+---
+sidebar_position: 4
+---
+
+# 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) 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) 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).
+
+## 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/_meta.json

@@ -0,0 +1 @@
+["css", "css-modules", "css-in-js", "tailwindcss"]

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

@@ -0,0 +1,69 @@
+# 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:
+
+import { PackageManagerTabs } from '@theme';
+
+<PackageManagerTabs
+  command={{
+    npm: 'npm install @modern-js/plugin-styled-components styled-components -D',
+    yarn: 'yarn add @modern-js/plugin-styled-components styled-components -D',
+    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.
+:::