Merge pull request #3265 from alibaba/release-next

docs/guide/advance/antd.md

@@ -1,6 +1,6 @@
 ---
 title: 使用 antd 组件
-order: 12
+order: 13
 ---
 
 项目开发中如果使用 antd 组件作为基础 UI 组件，可以通过工程插件提供 antd 组件的按需加载和主题定制能力。

docs/guide/advance/assets-local.md

@@ -1,6 +1,6 @@
 ---
 title: CSS 网络资源本地化
-order: 10
+order: 11
 ---
 
 组件代码里有可能会依赖一些远程 CDN 的字体文件等，某些网络可能访问不了，出现这个问题有几种情况：

docs/guide/advance/auth.md

@@ -1,6 +1,6 @@
 ---
 title: 权限管理
-order: 7
+order: 8
 ---
 
 对于一个 Web 应用，权限管理是经常会涉及的需求之一，通常包含以下几种常见的权限管理类型：

docs/guide/advance/backend.md

@@ -1,6 +1,6 @@
 ---
 title: 后端应用集成
-order: 15
+order: 16
 ---
 
 > 如果是阿里内部同学，请参考 [文档](https://yuque.alibaba-inc.com/ice/rdy99p/rpivf3)

docs/guide/advance/code-splitting.md

@@ -1,6 +1,6 @@
 ---
 title: 代码分割 Code Splitting
-order: 5
+order: 6
 ---
 
 随着应用的增长，代码 bundle 的大小也将随之增长。为了避免因体积过大而导致加载时间过长，我们可以按照路由对代码进行分割成不同的代码块，然后当路由被访问的时候才加载对应的代码，能够显著地提高应用性能。

docs/guide/advance/error-boundaries.md

@@ -1,6 +1,6 @@
 ---
 title: 错误边界 Error Boundaries
-order: 6
+order: 7
 ---
 
 当某个组件出现 JavaScript 错误时不应该影响整个应用的渲染，为了解决这个问题，我们可以通过错误边界（Error Boundaries）进行处理。

docs/guide/advance/fusion.md

@@ -1,6 +1,6 @@
 ---
 title: 使用 fusion 组件
-order: 11
+order: 12
 ---
 
 项目开发中如果使用 `@alifd/next` 作为基础 UI 组件，可以通过 `build-plugin-fusion` 插件实现组件按需加载和样式主题等相关能力，飞冰官方的模板都是基于 Fusion 组件的，因此一般不需要开发者再手动引入。

docs/guide/advance/mock.md

@@ -1,6 +1,6 @@
 ---
 title: 本地 Mock 数据
-order: 8
+order: 9
 ---
 
 在前后端分离的开发中，Mock 数据是前端开发中很重要的一个环节，前端可以不必强依赖后端接口，只需要约定好对应的数据接口，前端可以通过 Mock 模拟数据先行开发，在后端接口开发完成后，只需要切换对应的接口地址即可，可以保证项目的同步开发。

docs/guide/advance/prerender.md

@@ -0,0 +1,130 @@
+---
+title: 构建时预渲染 Prerender
+order: 5
+---
+
+在某些业务场景下，需要更好的 SEO，提高首页加载速度等等，基于此 icejs 提供了构建时预渲染（Prerender）方案。
+
+## 安装插件
+
+```bash
+$ npm install build-plugin-prerender --save-dev
+```
+
+## 工程配置
+
+### 在 SPA 中
+
+项目目录结构
+
+```markdown
+├── src
+|  ├── app.ts
+|  ├── pages
+|  |  ├── About         # About 页面
+|  |  ├── Dashboard     # Dashboard 页面
+|  |  └── Home          # Home 页面
+|  └── routes.ts
+```
+
+在 build.json 中引入 `build-plugin-prerender` 并配置, 其中 `routes` 为需要渲染的路由。
+
+```json
+{
+  "plugins": [
+    [
+      "build-plugin-prerender",
+      {
+        "routes": [
+          "/",
+          "/about",
+          "/dashboard"
+        ]
+      }
+    ]
+  ]
+}
+```
+
+运行 `npm run build`，得到的构建产物如下：
+
+```markdown
+├── build
+|  ├── about
+|  |  └── index.html   # 预渲染得到的 HTML
+|  ├── dashboard
+|  |  └── index.html   # 预渲染得到的 HTML
+|  ├── favicon.png
+|  ├── index.html
+|  └── js
+|     └── index.js
+```
+
+通过静态服务启动，通过预渲染后的 HTML 截图如下：
+
+![prerender-html](https://img.alicdn.com/tfs/TB1kihJJYj1gK0jSZFOXXc7GpXa-1364-738.png)
+
+### 在 MPA 中
+
+项目目录结构
+
+```markdown
+├── public
+|  ├── dashboard.html
+|  └── index.html
+├── src
+|  └── pages
+|     ├── Dashboard    # Dashboard 页面
+|     └── Home         # Home 页面
+```
+
+首先确保在 `build.json` 中开启 MPA 应用配置，`build-plugin-prerender` 配置字段同上
+
+```json
+{
+  "mpa": true,
+  "plugins": [
+    [
+      "build-plugin-prerender",
+      {
+        "routes": [
+          "/about",
+          "/dashboard"
+        ]
+      }
+    ]
+  ]
+}
+```
+
+运行 `npm run build`，得到的构建产物如下：
+
+```markdown
+├── build
+|  ├── dashboard
+|  |  └── index.html
+|  ├── home
+|  |  └── index.html
+|  └── js
+|     ├── dashboard.js
+|     ├── home.js
+|     └── vendor.js
+```
+
+## 插件参数
+
+- routes: `string[]`，需要预渲染的路由。默认是 `['/']`。
+
+## 部署到 Nginx
+
+前端项目部署到 Nginx 时，可以在 Nginx 配置下加入以下内容，使得访问预渲染的路由时，可以获取到经过预渲染后的 HTML。
+
+```nginx
+location / {
+    root   www/web;
+    index  index.html index.htm;
+  + try_files $uri $uri/ /index.html;
+}
+```
+
+该功能为实验性功能，如遇到问题可通过飞冰钉钉群与我们反馈。

docs/guide/advance/proxy.md

@@ -1,6 +1,6 @@
 ---
 title: 本地 Proxy 方案
-order: 9
+order: 10
 ---
 
 本地开发场景下，访问页面的 url 是 `http://127.0.0.1:3333`，但是后端接口可能是其他 ip、域名或端口，此时就会产生跨域问题，导致无法调试，针对这个问题推荐两种代理方式：

docs/guide/advance/publish.md

@@ -1,6 +1,6 @@
 ---
 title: 前端资源发布
-order: 13
+order: 14
 ---
 
 > 如果是阿里内部同学，请参考 [文档](https://yuque.antfin-inc.com/ice/rdy99p/syvuzh)

docs/guide/advance/quality.md

@@ -1,6 +1,6 @@
 ---
 title: 代码质量保障
-order: 14
+order: 15
 ---
 
 为了保证代码质量，我们推荐使用 lint 相关的工具对代码进行检测，同时为了降低常规 lint 工具的使用成本，我们封装了 [@ice/spec](https://github.com/ice-lab/spec) 这个 npm 包。

docs/guide/advance/statistical.md

@@ -1,6 +1,6 @@
 ---
 title: 页面埋点统计数据
-order: 16
+order: 17
 ---
 
 > 阿里内部用户请参考：https://yuque.antfin-inc.com/ice/rdy99p/paswzc

docs/guide/develop/plugin-list.md

@@ -192,6 +192,33 @@ http://example.com/?smartDebug=true
 http://example.com/?smartDebug=true&debugPort=8080&debugPath=/dist/index.js&outputPath=dist
 ```
 
+## build-plugin-jsx-plus
+
+该插件支持了一种 JSX 扩展语法 JSX+，它能帮助业务开发者更爽更快地书写 JSX。JSX+ 不是一种新的概念，它是 JSX 基础上的扩展指令概念。
+
+- JSX 虽然语法灵活，但是大量的花括号 + JS 语法导致了上下文切换和代码可读性的下降，JSX+ 的指令很好的解决了这个问题
+- JSX 本质是 JS 表达式，在运行时阶段才可以计算出真实的 DOM 结构，JSX+ 引入了一部分静态模板特性可以满足编译优化
+- 不新创造实体，指令在社区中是已经被广泛接受的概念，对开发者更友好，语法糖的表达更简单
+- 统一一套 JSX+ 类似概念的语法规范，减少已存在和潜在的重复建设
+
+Install:
+
+```bash
+$ npm i --save-dev build-plugin-jsx-plus
+```
+
+### 基础用法
+
+```json
+{
+  "plugins": [
+    "build-plugin-jsx-plus"
+  ]
+}
+```
+
+详细使用请参考 [jsx-plus](https://github.com/jsx-plus/jsx-plus/blob/master/README.zh_CN.md)
+
 ## build-plugin-fast-refresh（实验性）
 
 > 体验优化的实验性插件，可根据实际情况按需使用。

examples/with-prerender-mpa/build.json

@@ -0,0 +1,21 @@
+{
+  "mpa": true,
+  "plugins": [
+    [
+      "build-plugin-prerender",
+      {
+        "routes": [
+          "/home",
+          "/dashboard"
+        ],
+        "minify": {
+          "collapseBooleanAttributes": false,
+          "collapseWhitespace": false
+        },
+        "renderer": {
+          "maxConcurrentRoutes": 4
+        }
+      }
+    ]
+  ]
+}

examples/with-prerender-mpa/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "exmaple-with-prerender-mpa",
+  "description": "",
+  "dependencies": {
+    "ice.js": "^1.0.11",
+    "react": "^16.4.1",
+    "react-dom": "^16.4.1",
+    "build-plugin-prerender": "^1.5.1"
+  },
+  "devDependencies": {
+    "@types/react": "^16.9.13",
+    "@types/react-dom": "^16.9.4"
+  },
+  "scripts": {
+    "start": "icejs start",
+    "build": "icejs build"
+  },
+  "engines": {
+    "node": ">=8.0.0"
+  }
+}

examples/with-prerender-mpa/public/dashboard.html

@@ -0,0 +1,16 @@
+<!DOCTYPE html>
+<html>
+
+<head>
+  <meta charset="utf-8" />
+  <meta http-equiv="x-ua-compatible" content="ie=edge,chrome=1" />
+  <meta name="viewport" content="width=device-width" />
+  <title>icejs · prerender mpa example</title>
+</head>
+
+<body>
+  <div>dashboard content of html template</div>
+  <div id="ice-container"></div>
+</body>
+
+</html>

examples/with-prerender-mpa/public/index.html

@@ -0,0 +1,15 @@
+<!DOCTYPE html>
+<html>
+
+<head>
+  <meta charset="utf-8" />
+  <meta http-equiv="x-ua-compatible" content="ie=edge,chrome=1" />
+  <meta name="viewport" content="width=device-width" />
+  <title>icejs · prerender mpa example</title>
+</head>
+
+<body>
+  <div id="ice-container"></div>
+</body>
+
+</html>

examples/with-prerender-mpa/sandbox.config.json

@@ -0,0 +1,6 @@
+{
+  "template": "node",
+  "container": {
+    "port": 3333
+  }
+}

examples/with-prerender-mpa/src/pages/Dashboard/app.ts

@@ -0,0 +1,10 @@
+import { createApp, IAppConfig } from 'ice';
+import routes from './routes';
+
+const appConfig: IAppConfig = {
+  router: {
+    routes
+  },
+};
+
+createApp(appConfig);

examples/with-prerender-mpa/src/pages/Dashboard/index.tsx

@@ -0,0 +1,18 @@
+import * as React from 'react';
+import { store } from 'ice/Dashboard';
+
+const Dashboard = () => {
+  const [pageState, pageActions] = store.useModel('counter');
+  return (
+    <>
+      <h2>Dashboard Page...</h2>
+      <div>
+        <button type="button" onClick={pageActions.increment}>+</button>
+        <span>{pageState.count}</span>
+        <button type="button" onClick={pageActions.decrement}>-</button>
+      </div>
+    </>
+  );
+};
+
+export default Dashboard;