@modern-js/app-tools 3.6.0 → 3.8.0

package/docs/guides/basic-features/render/ssg.md

@@ -0,0 +1,228 @@
+# Static Site Generation
+
+SSG (Static Site Generation) is a technical solution that generates complete static web pages at build time based on data and templates. This means that in a production environment, pages are pre-rendered with content and can be cached by a CDN. SSG can offer better performance and higher security for pages that do not require dynamic data.
+
+## Enabling SSG
+
+To enable SSG functionality in a Modern.js project, follow these steps to modify the code:
+
+1. Install SSG plugin dependencies
+
+If the SSG plugin is not yet installed in your project, install it first:
+
+```bash
+pnpm add @modern-js/plugin-ssg
+```
+
+:::tip Version Consistency
+
+Make sure the version of `@modern-js/plugin-ssg` 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/plugin-ssg`:
+
+```bash
+# Check the current version of @modern-js/app-tools
+pnpm list @modern-js/app-tools
+
+# Install the same version of @modern-js/plugin-ssg
+pnpm add @modern-js/plugin-ssg@<version>
+```
+
+:::
+
+2. Configure modern.config.ts
+
+Import and add the SSG plugin in the `modern.config.ts` file, and configure `output.ssg`:
+
+```ts title="modern.config.ts"
+import { defineConfig, appTools } from '@modern-js/app-tools';
+import { ssgPlugin } from '@modern-js/plugin-ssg';
+
+export default defineConfig({
+  plugins: [appTools(), ssgPlugin()],
+  output: {
+    ssg: true,
+  },
+});
+```
+
+:::info Scope of Application
+
+- Use `output.ssg` for single-entry apps.
+- Use `output.ssgByEntries` for multi-entry apps.
+- When only `output.ssg: true` is set and `output.ssgByEntries` is not configured, all routes under all entries will be treated as SSG routes.
+
+:::
+
+## Development Debugging
+
+Since SSG also renders pages in a Node.js environment, we can enable SSR during the **development phase** to expose code issues early and validate the SSG rendering effect:
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  server: {
+    ssr: process.env.NODE_ENV === 'development',
+  }
+}
+```
+
+## Using SSG in Conventional Routing
+
+In **conventional routing**, Modern.js generates routes based on the file structure under the entry point, allowing the framework to collect complete route information.
+
+### Basic Usage
+
+For example, the following is a project directory structure using conventional routing:
+
+```bash
+.
+└── routes
+    ├── layout.tsx
+    ├── page.tsx
+    └── user
+        ├── layout.tsx
+        ├── page.tsx
+        └── profile
+            └── page.tsx
+```
+
+The above file directory will generate the following three routes:
+
+- `/`
+- `/user`
+- `/user/profile`
+
+:::tip
+If you are not familiar with the rules of conventional routing, refer to the [Routing Solution](/guides/basic-features/routes/routes.md) first.
+
+:::
+
+Add component code in `src/routes/page.tsx`:
+
+```jsx title="src/routes/page.tsx"
+export default () => {
+  return <div>Index Page</div>;
+};
+```
+
+Run the command `pnpm run dev` at the project root and check the `dist/` directory, where only one HTML file `main/index.html` is generated.
+
+Run the command `pnpm run build` at the project root, and after the build completes, check the `dist/` directory again. This time, you'll find `main/index.html`, `main/user/index.html`, and `main/user/profile/index.html` files, each corresponding to the routes listed above.
+
+Each route in **conventional routing** will generate a separate HTML file. Checking `main/index.html`, you will find it contains the text `Index Page`, which demonstrates the effect of SSG.
+
+After running `pnpm run serve` to start the project, inspect the returned document in the Network tab of the browser's development tools. The document includes the fully rendered content from the component.
+
+## Using SSG in Manual Routing
+
+**Manual routing** defines routes through component code, requiring the application to run to obtain accurate route information. Therefore, you cannot use the SSG feature out of the box. Developers need to configure which routes require SSG.
+
+For example, consider the following code with multiple routes. By setting `output.ssg` to `true`, it will only render the entry route (`/`) by default.
+
+```tsx title="src/App.tsx"
+import { BrowserRouter, Route, Routes } from '@modern-js/runtime/router';
+import { StaticRouter } from '@modern-js/runtime/router/server';
+import { use } from 'react';
+import { RuntimeContext } from '@modern-js/runtime';
+
+const Router = typeof window === 'undefined' ? StaticRouter : BrowserRouter;
+
+export default () => {
+  const context = use(RuntimeContext);
+  const pathname = context?.request?.pathname;
+  return (
+    <Router location={pathname}>
+      <Routes>
+        <Route index element={<div>index</div>} />
+        <Route path="about" element={<div>about</div>} />
+      </Routes>
+    </Router>
+  );
+};
+```
+
+If you want to enable SSG for `/about` as well, you can configure `output.ssg`:
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  output: {
+    ssg: {
+      routes: ['/', '/about'],
+    },
+  },
+});
+```
+
+After running `pnpm run build`, you will see a new `main/about/index.html` file in the `dist/` directory.
+
+After running `pnpm run serve` to start the project, inspect the returned document in the Network tab of the browser's development tools. The document includes the fully rendered content from the component.
+
+:::info
+The above example introduces single-entry scenarios. For more information, refer to the [API Documentation](/configure/app/output/ssg.md).
+:::
+
+## Adding Dynamic Routes
+
+In manual routing or conventional routing with dynamic segments (e.g., `/user/[id]`), provide concrete paths directly in `routes`.
+
+```js
+export default defineConfig({
+  output: {
+    ssg: {
+      routes: ['/', '/about', '/user/modernjs'],
+    },
+  },
+});
+```
+
+## Multi-entry
+
+For multi-entry apps, configure per entry via `output.ssgByEntries`:
+
+```js
+export default defineConfig({
+  output: {
+    ssgByEntries: {
+      home: {
+        routes: ['/', '/about', '/user/modernjs'],
+      },
+      admin: false,
+    },
+  },
+});
+```
+
+:::info
+See API details: [output.ssgByEntries](/configure/app/output/ssgByEntries.md)
+:::
+
+## Configuring Request Headers for Rendering
+
+Modern.js supports configuring request headers for specific entries or routes. For example:
+
+```js
+export default defineConfig({
+  output: {
+    ssg: {
+      headers: {
+        'x-tt-env': 'ppe_modernjs',
+      },
+      routes: [
+        '/',
+        {
+          url: '/about',
+          headers: {
+            from: 'modern-website',
+          },
+        },
+      ],
+    },
+  },
+});
+```
+
+In the above configuration, the `x-tt-env` request header is set for all routes, and the `from` request header is specifically set for the `/about` route.
+
+:::tip
+Headers set in routes will override headers set for entries.
+:::

package/docs/guides/basic-features/render/ssr-cache.md

@@ -0,0 +1,201 @@
+# Rendering Cache
+
+When developing applications, sometimes we cache computation results using hooks like React's `useMemo` and `useCallback`. By leveraging caching, we can reduce the number of computations, thus saving CPU resources and improving user experience.
+
+Modern.js supports caching server-side rendering (SSR) results, reducing the computational and rendering time during subsequent requests. This accelerates page load time and improves user experience. Additionally, caching lowers server load, conserves computational resources, and speeds up user access.
+
+## Configuration
+
+Create a `server/cache.[t|j]s` file in your application and export the `cacheOption` configuration to enable SSR rendering cache:
+
+```ts title="server/cache.ts"
+import type { CacheOption } from '@modern-js/server-runtime';
+
+export const cacheOption: CacheOption = {
+  maxAge: 500, // ms
+  staleWhileRevalidate: 1000, // ms
+};
+```
+
+## Configuration Details
+
+### Cache Configuration
+
+The caching strategy implements [stale-while-revalidate](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control).
+
+Within the `maxAge` period, the cache content is directly returned. Exceeding `maxAge` but within `staleWhileRevalidate`, the cache content is still returned directly, but it re-renders asynchronously.
+
+**Object Type**
+
+```ts
+export interface CacheControl {
+  maxAge: number;
+  staleWhileRevalidate: number;
+  customKey?: string | ((pathname: string) => string);
+}
+```
+
+Here, `customKey` is the custom cache key. By default, Modern.js uses the request `pathname` as the cache key, but developers can define it when necessary.
+
+**Function Type**
+
+```ts
+export type CacheOptionProvider = (
+  req: IncomingMessage,
+) => Promise<CacheControl | false> | CacheControl | false;
+```
+
+Sometimes, developers need to use `req` to customize the cache key, or prevent caching for specific URLs. You can configure this as a function, as shown:
+
+```ts title="server/cache.ts"
+import type { CacheOption, CacheOptionProvider } from '@modern-js/server-runtime';
+
+const provider: CacheOptionProvider = (req) => {
+  const { url, headers, ... } = req;
+  if(url.includes('no-cache=1')) {
+    return false;
+  }
+
+  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, different routes require different caching strategies. We also offer a mapping configuration method, as shown below:
+
+```ts title="server/cache.ts"
+import type { CacheOption } from '@modern-js/server-runtime';
+
+export const cacheOption: CacheOption = {
+  '/home': {
+    maxAge: 50,
+    staleWhileRevalidate: 100,
+  },
+  '/about': {
+    maxAge: 1000 * 60 * 60 * 24, // one day
+    staleWhileRevalidate: 1000 * 60 * 60 * 24 * 2 // two days
+  },
+  '*': (req) => { // If no above route matches, this applies
+    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 `/home` and `/about` are patterns, meaning `/home/abc` will also match. You can use regex in these patterns, such as `/home/.+`.
+
+### Cache Container
+
+By default, the server uses memory for caching. Typically, services are deployed in a Serverless container, creating a new process for each access, making it impossible to use the previous cache.
+
+Thus, Modern.js allows developers to define custom cache containers. Containers must implement the `Container` interface:
+
+```ts
+export interface Container<K = string, V = string> {
+  /**
+   * Returns a specified element from the container. 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 Container.
+   * @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 container. 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 container existed and has been removed, or false if the element does not exist.
+   */
+  delete: (key: K) => Promise<boolean>;
+}
+```
+
+Developers can implement a Redis cache container as shown below:
+
+```ts
+import Redis from 'ioredis';
+import type { Container, CacheOption } from '@modern-js/server-runtime';
+
+class RedisContainer implements Container {
+  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.exists(key) > 0;
+  }
+
+  async delete(key: string): Promise<boolean> {
+    return this.redis.del(key) > 0;
+  }
+}
+
+const container = new RedisContainer();
+
+export const customContainer: Container = container;
+
+export const cacheOption: CacheOption = {
+  maxAge: 500, // ms
+  staleWhileRevalidate: 1000, // ms
+};
+```
+
+## Cache Identification
+
+When rendering cache is enabled, Modern.js identifies the cache status of the current request through the `x-render-cache` response header. Here's an example response:
+
+```bash
+< HTTP/1.1 200 OK
+< Access-Control-Allow-Origin: *
+< content-type: text/html; charset=utf-8
+< x-render-cache: hit
+< Date: Thu, 29 Feb 2024 02:46:49 GMT
+< Connection: keep-alive
+< Keep-Alive: timeout=5
+< Content-Length: 2937
+```
+
+The `x-render-cache` header can have the following values:
+
+| Name    | Description                                                                         |
+| ------- | ----------------------------------------------------------------------------------- |
+| hit     | Cache hit, returned cache content                                                   |
+| stale   | Cache hit, but data is stale, returned cache content and re-rendered asynchronously |
+| expired | Cache expired, re-rendered and returned new content                                 |
+| miss    | Cache missed                                                                        |