@modern-js/main-doc 2.42.1 → 2.43.0

package/docs/en/apis/app/runtime/web-server/middleware.mdx

@@ -91,7 +91,7 @@ The execution of the `next` function does not affect built-in processes, only co
 ```ts
 export const Middleware = () => async (ctx, next) => {
   const start = Date.now();
-  ctx.res.once('finish', () => {
+  ctx.source.res.once('finish', () => {
     console.log(Date.now() - start);
   });
 };
@@ -103,8 +103,8 @@ Modern.js provides `res.locals` to store local variables for the current request
 
 ```ts
 export const Middleware = () => async (ctx, next) => {
-  ctx.res.locals.id = 'Modern.js';
-  ctx.res.locals.rpc = createRpcInstance();
+  ctx.response.locals.id = 'Modern.js';
+  ctx.response.locals.rpc = createRpcInstance();
 };
 ```
 

package/docs/en/configure/app/server/ssr.mdx

@@ -30,6 +30,7 @@ When the value type is `Object`, the following properties can be configured:
 - `inlineScript`: `boolean = true`, by default, SSR data is injected into HTML as inline scripts and assigned directly to global variables. Configure `false` to distribute JSON instead of assigning to global variables.
 - `disablePrerender`: `boolean = fasle`, To ensure compatibility with the old data request method (`useLoader`), by default, Modern.js performs pre-rendering of components.
   However, if developers want to reduce one rendering when there is no use of the useLoader API in your project, you can set the configuration `disablePrerender=true`.
+- `unsafeHeaders`: `string[] = []`, For safety reasons, Modern.js does not add excessive content to SSR_DATA. Developers can use this configuration to specify the headers that need to be injected.
 
 ```ts title="modern.config.ts"
 export default defineConfig({
@@ -38,6 +39,7 @@ export default defineConfig({
       forceCSR: true,
       mode: 'stream',
       inlineScript: false,
+      unsafeHeaders: ['User-Agent'],
     },
   },
 });

package/docs/en/guides/advanced-features/inline-assets.mdx

@@ -0,0 +1,161 @@
+---
+sidebar_position: 13
+---
+
+# Inline Static Assets
+
+Inline static assets refer to the practice of including the content of a static asset directly in a HTML or JS file, instead of linking to an external file. This can improve the performance of a website by reducing the number of HTTP requests that the browser has to make to load the page.
+
+However, static assets inlining also has some disadvantages, such as increasing the size of a single file, which may lead to slower loading. Therefore, in the actual scenario, it is necessary to decide whether to use static assets inlining according to the specific situation.
+
+Modern.js will automatically inline static assets that are less than 10KB, but sometimes you may need to manually control assets to force them to be inlined or not, and this document explains how to precisely control the inlining behavior of static assets.
+
+## Automatic Inlining
+
+By default, Modern.js will inline assets when the file size of is less than a threshold (the default is 10KB). When inlined, the asset will be converted to a Base64 encoded string and will no longer send a separate HTTP request. When the file size is greater than this threshold, it is loaded as a separate file with a separate HTTP request.
+
+The threshold can be modified with the [output.dataUriLimit](/configure/app/output/data-uri-limit) config. For example, set the threshold of images to 5000 Bytes, and set media assets not to be inlined:
+
+```ts
+export default {
+  output: {
+    dataUriLimit: {
+      image: 5000,
+      media: 0,
+    },
+  },
+};
+```
+
+## Force Inlining
+
+You can force an asset to be inlined by adding the `inline` query when importing the asset, regardless of whether the asset's size is smaller than the size threshold.
+
+```tsx
+import React from 'react';
+import img from '. /foo.png?inline';
+
+export default function Foo() {
+  return <img src={img} />;
+}
+```
+
+In the above example, the `foo.png` image will always be inlined, regardless of whether the size of the image is larger than the threshold.
+
+In addition to the `inline` query, you can also use the `__inline` query to force inlining of the asset:
+
+```tsx
+import img from '. /foo.png?__inline';
+```
+
+### Referenced from CSS file
+
+When you reference a static asset in your CSS file, you can also force inline the asset with the `inline` or `__inline` queries.
+
+```css
+.foo {
+  background-image: url('. /icon.png?inline');
+}
+```
+
+:::tip Do you really need to force inlining?
+Inline large assets will significantly increase the first paint time or first contentful paint time of a page, which will hurt user experience. And when you inline a static asset multiple times into a CSS file, the base64 content will be repeatedly injected, causing the bundle size to grow . Please use forced inlining with caution.
+:::
+
+## Force no inlining
+
+When you want to always treat some assets as separate files, no matter how small the asset is, you can add the `url` query to force the asset not to be inlined.
+
+```tsx
+import React from 'react';
+import img from '. /foo.png?url';
+
+export default function Foo() {
+  return <img src={img} />;
+}
+```
+
+In the above example, the `foo.png` image will always be loaded as a separate file, even if the size of the image is smaller than the threshold.
+
+In addition to the `url` query, you can also use the `__inline=false` query to force the asset not to be inlined:
+
+```tsx
+import img from '. /foo.png?__inline=false';
+```
+
+### Referenced from CSS file
+
+When you reference a static asset in your CSS file, you can also force the asset not to be inlined with `url` or `__inline=false` queries.
+
+```css
+.foo {
+  background-image: url('. /icon.png?url');
+}
+```
+
+:::tip Do you really need to exclude assets from inlining?
+Excluding assets from inlining will increase the number of assets that the Web App needs to load. This will reduce the efficiency of loading assets in a weak network environment or in scenarios where HTTP2 is not enabled. Please use force no Inline with caution.
+
+## Inline JS files
+
+In addition to inlining static assets into JS files, Modern.js also supports inlining JS files into HTML files.
+
+Just enable the [output.enableInlineScripts](/configure/app/output/enable-inline-scripts) config, and the generated JS files will not be written into the output directory, but will be directly inlined to the corresponding in the HTML file.
+
+```ts
+export default {
+  output: {
+    enableInlineScripts: true,
+  },
+};
+```
+
+:::tip
+Inline JS files may cause the single HTML file to be too large, and it will break the HTTP caching. Please use it with caution.
+:::
+
+## Inline CSS files
+
+You can also inline CSS files into HTML files.
+
+Just enable the [output.enableInlineStyles](/configure/app/output/enable-inline-styles) config, the generated CSS file will not be written into the output directory, but will be directly inlined to the corresponding in the HTML file.
+
+```ts
+export default {
+  output: {
+    enableInlineStyles: true,
+  },
+};
+```
+
+## Add Type Declaration
+
+When you use URL queries such as `?inline` and `?url` in TypeScript code, TypeScript may prompt that the module is missing a type definition:
+
+```
+TS2307: Cannot find module './logo.png?inline' or its corresponding type declarations.
+```
+
+To fix this, you can add type declarations for these URL queries, please create `src/global.d.ts` file and add the following type declarations:
+
+```ts
+declare module '*?inline' {
+  const content: string;
+  export default content;
+}
+
+declare module '*?inline' {
+  const content: string;
+  export default content;
+}
+
+declare module '*?__inline' {
+  const content: string;
+  export default content;
+}
+
+declare module '*?inline=false' {
+  const content: string;
+  export default content;
+}
+```

package/docs/en/guides/advanced-features/optimize-bundle.mdx

@@ -44,9 +44,9 @@ See the [performance.bundleAnalyze](/configure/app/performance/bundle-analyze.ht
 
 ## Adjust Browserslist
 
-The Builder will compile the code according to the project's Browserslist config, and inject some Polyfills. If the project does not need to be compatible with legacy browsers, you can adjust the Browserslist and drop some legacy browsers, thereby reducing the compilation overhead on syntax and polyfill.
+Modern.js will compile the code according to the project's Browserslist config, and inject some Polyfills. If the project does not need to be compatible with legacy browsers, you can adjust the Browserslist and drop some legacy browsers, thereby reducing the compilation overhead on syntax and polyfill.
 
-Builder's default Browserslist config is:
+Modern.js's default Browserslist config is:
 
 ```js
 ['> 0.01%', 'not dead', 'not op_mini all'];
@@ -66,7 +66,7 @@ Please read the [Browserslist](https://modernjs.dev/builder/en/guide/advanced/br
 
 When it is clear that third-party dependencies do not require additional polyfill, you can set [output.polyfill](/configure/app/output/polyfill.html) to `usage`.
 
-In `usage` mode, Builder analyzes the syntax used in the source code and injects the required polyfill code on demand to reduce the size of polyfill.
+In `usage` mode, Modern.js analyzes the syntax used in the source code and injects the required polyfill code on demand to reduce the size of polyfill.
 
 ```js
 export default {
@@ -77,18 +77,19 @@ export default {
 ```
 
 :::tip
-Please read the [Browser Compatibility](https://modernjs.dev/builder/en/guide/advanced/browser-compatibility.html) chapter to know more about the usage of Browserslist.
+Please read the [Browser Compatibility](/guides/advanced-features/compatibility) chapter to know more about the usage of Browserslist.
 :::
 
 ## Image Compression
 
 In general front-end projects, the size of image often accounts for a large proportion of the total bundle size of the project.So if the image size can be reduced as much as possible, it will have a significant optimization effect on the project bundle size. You can enable image compression by registering a plugin in the Builder:
 
-```js
+```ts title="modern.config.ts"
 import { builderPluginImageCompress } from '@modern-js/builder-plugin-image-compress';
 
-// Add the plugin to the Builder
-builder.addPlugins([builderPluginImageCompress()]);
+export default {
+  builderPlugins: [builderPluginImageCompress()],
+};
 ```
 
 See details in [plugin-image-compress](https://modernjs.dev/builder/en/plugins/plugin-image-compress.html).

package/docs/en/guides/advanced-features/ssr/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "SSR",
+  "position": 3,
+  "link": {
+    "type": "doc",
+    "id": "guides/advanced-features/ssr/index"
+  }
+}

package/docs/en/guides/advanced-features/ssr/cache.mdx

@@ -0,0 +1,186 @@
+---
+sidebar_position: 3
+title: Cache
+---
+
+# Render Cache
+
+Sometimes we cache computation results, such as with the React useMemo, useCallback Hook. By caching, we can reduce the number of computations, thus reducing CPU resource usage and enhancing the user experience.
+
+Caching the results of server-side rendering (SSR) can reduce the computation and rendering time for each server request, enabling faster page load speeds and improving the user experience. It also lowers the server load, saves computational resources, and speeds up user access.
+
+:::info
+Need x.43.0+
+:::
+
+## Configuration
+
+You can enable caching by configuring it in `server/cache.[t|j]s`:
+
+```ts title="server/cache.ts"
+import type { CacheOption } from '@modern-js/runtime/server';
+
+export const cacheOption: CacheOption = {
+  maxAge: 500, // ms
+  staleWhileRevalidate: 1000, // ms
+};
+```
+
+## Configuration Explanation
+
+### Cache Configuration
+
+The caching policy is implemented based on [stale-while-revalidate](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control).
+
+During the `maxAge` period, cache content will be returned directly. After `maxAge` but within `staleWhileRevalidate`, the cache content will also be returned directly, but at the same time, re-rendering will be executed asynchronously.
+
+**Object type**
+
+```ts
+export interface CacheControl {
+  maxAge: number;
+
+  staleWhileRevalidate: number;
+
+  customKey?: string | ((pathname: string) => string);
+}
+```
+
+In this, customKey is used for custom cache key. By default, Modern.js will use the request pathname as key for caching, but in some cases, this may not meet your needs, so developers can customise it.
+
+**Function type**
+
+```ts
+export type CacheOptionProvider = (
+  req: IncomingMessage,
+) => Promise<CacheControl> | CacheControl;
+```
+
+Sometimes developers need to customise the cache key through req, which can be handled using the function form, as shown in the following code:
+
+```ts title="server/cache.ts"
+import type { CacheOption, CacheOptionProvider } from '@modern-js/runtime/server';
+
+const provider: CacheOptionProvider = (req) => {
+  const { url, headers, ... } = req;
+
+  const key = computedKey(url, headers, ...);
+
+  return {
+    maxAge: 500, // ms
+    staleWhileRevalidate: 1000, // ms
+    customKey: key,
+  }
+}
+
+export const cacheOption: CacheOption = provider;
+```
+
+**Mapping type**
+
+```ts
+export type CacheOptions = Record<string, CacheControl | CacheOptionProvider>;
+```
+
+Sometimes, developers need to apply different caching policies for different routes. We also provide a mapping way for configuration, as shown in example below:
+
+```ts title="server/cache.ts"
+import type { CacheOption } from '@modern-js/runtime/server';
+
+export const cacheOption: CacheOption = {
+  '/home': {
+    maxAge: 50,
+    staleWhileRevalidate: 100,
+  },
+  '/about': {
+    maxAge: 1000 * 60 * 60 * 24, // one day
+    staleWhileRevalidate: 1000 * 60 * 60 * 24 * 2 // two day
+  },
+  '*': (req) => { // If the above routes cannot be matched, it will match to '*'
+    const { url, headers, ... } = req;
+    const key = computedKey(url, headers, ...);
+
+    return {
+      maxAge: 500,
+      staleWhileRevalidate: 1000,
+      customKey: key,
+    }
+  }
+}
+```
+
+- The route `http://xxx/home` will apply the first rule.
+- The route `http://xxx/about` will apply the second rule.
+- The route `http://xxx/abc` will apply the last rule.
+
+The above-mentioned `/home` and `/about` will be used as patterns for matching, which means that `/home/abc` will also comply with this rule.
+Simultaneously, you can also include regular expression syntax in it, such as `/home/.+`.
+
+### Cache Container
+
+By default, Server will use memory for caching. But typically, services will be deployed on serverless. Each service access may be a new process, so caching cannot be applied every time.
+
+Therefore, developers can also customise the cache container, which needs to implement the `Containter` interface.
+
+```ts
+export interface Containter<K = string, V = string> {
+  /**
+   * Returns a specified element from the containter. If the value that is associated to the provided key is an object, then you will get a reference to that object and any change made to that object will effectively modify it inside the Containter.
+   * @returns Returns the element associated with the specified key. If no element is associated with the specified key, undefined is returned.
+   */
+  get: (key: K) => Promise<V | undefined>;
+
+  /**
+   * Adds a new element with a specified key and value to the containter. If an element with the same key already exists, the element will be updated.
+   *
+   * The ttl indicates cache expiration time.
+   */
+  set: (key: K, value: V, options?: { ttl?: number }) => Promise<this>;
+
+  /**
+   * @returns boolean indicating whether an element with the specified key exists or not.
+   */
+  has: (key: K) => Promise<boolean>;
+
+  /**
+   * @returns true if an element in the containter existed and has been removed, or false if the element does not exist.
+   */
+  delete: (key: K) => Promise<boolean>;
+}
+```
+
+As an example in the following code, a developer can implement a Redis container.
+
+```ts
+import type { Containter, CacheOption } from '@modern-js/runtime/server';
+
+class RedisContainter implements Containter {
+  redis = new Redis();
+
+  async get(key: string) {
+    return this.redis.get(key);
+  }
+
+  async set(key: string, value: string): Promise<this> {
+    this.redis.set(key, value);
+    return this;
+  }
+
+  async has(key: string): Promise<boolean> {
+    return this.redis.has(key);
+  }
+
+  async delete(key: string): Promise<boolean> {
+    return this.redis.delete(key);
+  }
+}
+
+const containter = new RedisContainter();
+
+export const customContainer: Containter = containter;
+
+export const cacheOption: CacheOption = {
+  maxAge: 500, // ms
+  staleWhileRevalidate: 1000, // ms
+};
+```

package/docs/en/guides/advanced-features/ssr/index.mdx

@@ -0,0 +1,22 @@
+# SSR
+
+By rendering the HTML content of web pages into complete web pages on the server side, and then sending the generated web pages to the client, the client only needs to display the web pages without further rendering.
+
+Its main advantages are:
+
+- Improve first screen load speed: SSR can generate complete websites on the server side, the client only needs to download the content of the website, no additional renderings are required, thus improving the first screen load speed.
+- Improve user experience: SSR can improve the responsiveness of web pages, thereby enhancing the user experience.
+- Good for SEO: SSR can generate complete HTML content. Search engines can directly index HTML content to improve website ranking.
+
+If you have the following scenarios, developers can consider using SSR to render your pages:
+
+1. Websites with higher first-screen loading speed requirements, such as e-commerce websites, news websites, etc.
+2. Websites with higher user experience requirements, such as social networking sites, gaming sites, etc.
+3. Websites with higher SEO requirements, such as corporate websites, blogs, etc.
+
+In Modern.js, SSR is also out-of-the-box. Developers do not need to write complex server-side logic for SSR, nor do they need to worry about the operation and maintenance of SSR, or create separate services.
+In addition to the out-of-the-box SSR service, to ensure the developer's development experience, we also have:
+
+- A complete SSR downgrade strategy to ensure that the page can run safely.
+- Automatically split sub-routes to load on demand, reducing the size of the first screen resources.
+- Built-in caching system to solve the problem of high server-side load.