Merge pull request #243 from NervJS/feat/4.x-cli-vite

Feat/4.x cli vite

Author: ZEJIA-LIU

docs/cli.md

@@ -51,9 +51,24 @@ Taro Doctor 就像一个医生一样，可以诊断项目的依赖、设置、
 
 ### 快速创建新页面
 
-Taro create --name [页面名称] 能够在当前项目的 pages 目录下快速生成新的页面文件，并填充基础代码，是一个提高开发效率的利器。
+Taro create --name [页面名称] --dir [路径] --subpkg [分包路径]  能够在当前项目的指定目录下快速生成新的页面文件，并填充基础代码，是一个提高开发效率的利器。
 
-> taro 会尝试同步修改 `app.config.js` 配置文件中的 `pages` 字段。
+> taro 会尝试同步修改 `app.config.js` 配置文件中的 `pages` 或者 `subPackages` 字段。
+
+#### 例子
+假设当前当前跟路径为 `/project/root`。
+
+执行下面命令创建主包页面：
+```bash
+taro create newPage --dir pages/mydir
+```
+那么会在 `/project/root/src/pages/mydir` 目录下生成新的页面，并且在 `app.config.js` 中自动补齐 `pages` 字段。
+
+执行下面命令创建分包页面：
+```bash
+taro create newPage --subpkg mysubpages
+```
+那么会在 `/project/root/src/mysubpages` 目录下生成新的页面，并且在 `app.config.js` 中自动补齐 `subPackages` 字段。
 
 ### 快速创建插件模版
 

docs/config-detail.md

@@ -504,21 +504,24 @@ module.exports = {
 
 :::info
 Taro v3.5 开始支持。
+
+
+Taro v4.0.0 开始支持 `vite` 值。
 :::
 
 `string | object`
 
 默认值：`'webpack4'`
 
-使用的编译工具。可选值：`webpack4`、`webpack5`。
+使用的编译工具。可选值：`webpack4`、`webpack5`、`vite`。
 
 取值也可以是对象，此时可以对针对特定的编译器作额外的配置：
 
 ### compiler.type
 
 `string`
 
-使用的编译工具。可选值：`webpack4`、`webpack5`。
+使用的编译工具。可选值：`webpack4`、`webpack5`、`vite`。
 
 ### compiler.errorLevel
 
@@ -609,6 +612,14 @@ webpack 编译过程中的错误类型主要如下两类：1、致命的 wepback
 
 不需要执行预编译的依赖。
 
+### compiler.vitePlugins
+
+> 只有 vite 支持
+
+`array`
+
+vite 插件
+
 ## cache
 
 :::info
@@ -917,13 +928,13 @@ module.exports = {
           selectorBlackList: ['body'],
         },
       },
-      // 小程序端样式引用本地资源内联
-      url: {
-        enable: true,
-        config: {
-          maxSize: 10, // 设定转换尺寸上限（单位：kbytes）
-        },
-      },
+      // 小程序端样式引用本地资源内联 该属性在 v4.0.0 版本已废弃，小程序端默认全部转换
+      // url: {
+      //   enable: true,
+      //   config: {
+      //     maxSize: 10, // 设定转换尺寸上限（单位：kbytes）
+      //   },
+      // },
       // css modules 功能开关与相关配置
       cssModules: {
         enable: false, // 默认为 false，如需使用 css modules 功能，则设为 true
@@ -1268,7 +1279,10 @@ module.exports = {
 
 `object`
 
-可用于修改、拓展 Webpack 的 **output** 选项，配置项参考[官方文档](https://webpack.js.org/configuration/output/)。
+可用于修改、拓展 Webpack 的 **output** 选项，配置项参考[webpack官方文档](https://webpack.js.org/configuration/output/)。
+
+vite 编译环境下用于修改、扩展 rollup 的 output，目前仅适配 chunkFileNames 和 assetFileNames 两个配置，修改其他配置请使用 vite 插件进行修改。配置想参考[官方文档](https://rollupjs.org/configuration-options/)
+
 
 ```js
 module.exports = {
@@ -1888,6 +1902,18 @@ module.exports = {
 
 针对 `woff | woff2 | eot | ttf | otf` 文件的 `url-loader` 配置。配置项参考[官方文档](https://github.com/webpack-contrib/url-loader)。
 
+### h5.legacy
+
+:::info
+Taro v4.0.0 开始支持。
+:::
+
+`boolean`
+
+默认值 `false`
+
+选择 `vite` 编译器的情况下才会使用到该字段。生成的代码是否要兼容旧版浏览器，值为 true 时，会去读取 package.json 的 browserslist 字段。
+
 ## rn
 
 专属于 RN 的配置。

docs/config.md

@@ -49,13 +49,6 @@ const config = {
       autoprefixer: {
         enable: true,
       },
-      // 小程序端样式引用本地资源内联配置
-      url: {
-        enable: true,
-        config: {
-          limit: 10240,
-        },
-      },
       cssModules: {
         enable: false, // 默认为 false，如需使用 css modules 功能，则设为 true
         config: {
@@ -102,6 +95,8 @@ module.exports = function (merge) {
 :::info
 Taro v3.6.9 开始支持
 
+Taro v4.0.0 之后支持范型，可以传入编译器类型 'webpack4 | 'webpack5 |  'vite'
+
 react native 暂不支持
 :::
 
@@ -113,7 +108,7 @@ react native 暂不支持
 // config/index.ts
 import { defineConfig } from '@tarojs/cli'
 
-export default defineConfig({
+export default defineConfig<T>({
   // ...Taro 配置
 })
 ```
@@ -126,7 +121,7 @@ import type { UserConfigExport } from '@tarojs/cli'
 
 export default {
   // ...Taro 配置
-} satisfies UserConfigExport
+} satisfies UserConfigExport<T>
 ```
 
 ### 异步配置

docs/template.md

@@ -83,21 +83,35 @@ zip 包解压出单文件夹，文件夹内包含若干模板。
 
 很多情况下需要为模板加入一些逻辑，从而根据不同的环境生成不同的模板内容。
 
-开发者可以在模板根目录加入 **template_creator.js** 文件，文件对外 exports 包含 handler 与 basePageFiles 字段的对象：
+开发者可以在模板根目录加入 **template_creator.js** 文件，文件对外 exports 包含 handler 、 basePageFiles 与 compiler 字段的对象：
 
 ```js {5,16} title="template_creator.js"
-function createWhenTs(params) {
+const path = require('path')
+
+function normalizePath (path) {
+  return path.replace(/\\/g, '/').replace(/\/{2,}/g, '/')
+}
+
+function createWhenTs(err, params) {
   return params.typescript ? true : false
 }
+const SOURCE_ENTRY = '/src'
+const PAGES_ENTRY = '/src/pages'
 
 const handler = {
   '/global.d.ts': createWhenTs,
   '/tsconfig.json': createWhenTs,
-  '/src/pages/index/index.jsx'({ pageName }) {
-    return { setPageName: `/src/pages/${pageName}/${pageName}.jsx` }
+  '/src/pages/index/index.jsx' (err, { pageName = '', pageDir = '', subPkg = '' }) {
+    return {
+      setPageName: normalizePath(path.join(PAGES_ENTRY, pageDir, pageName, 'index.jsx')),
+      setSubPkgName: normalizePath(path.join(SOURCE_ENTRY, subPkg, pageDir, pageName, 'index.jsx'))
+    }
   },
-  '/src/pages/index/index.css'({ pageName }) {
-    return { setPageName: `/src/pages/${pageName}/${pageName}.css` }
+  '/src/pages/index/index.css' (err, { pageName = '', pageDir = '', subPkg = '' }) {
+    return {
+      setPageName: normalizePath(path.join(PAGES_ENTRY, pageDir, pageName, 'index.css')),
+      setSubPkgName: normalizePath(path.join(SOURCE_ENTRY, subPkg, pageDir, pageName, 'index.css'))
+    }
   },
 }
 
@@ -106,12 +120,13 @@ const basePageFiles = ['/src/pages/index/index.jsx', '/src/pages/index/index.css
 module.exports = {
   handler,
   basePageFiles,
+  compiler: ['Webpack5', 'Webpack4', 'Wite']
 }
 ```
 
 #### 模板语言
 
-请使用 [ejs](https://ejs.co/) 作为模板语言，各模板文件都将接收到全局模板参数。
+请使用 [Handlebars](https://handlebarsjs.com/) 作为模板语言，各模板文件都将接收到全局模板参数。
 
 ##### 默认全局模板参数（模板中可直接使用的变量）
 
@@ -121,22 +136,18 @@ module.exports = {
 | description | string                                 | 项目描述                                     |
 | version     | string                                 | Taro CLI 版本                                |
 | date        | string                                 | 模板创建时间戳                               |
-| css         | 'none' or 'sass' or 'stylus' or 'less' | 样式预处理工具                               |
+| css         | 'None' or 'Sass' or 'Stylus' or 'Less' | 样式预处理工具                               |
 | cssExt      | string                                 | 样式文件后缀                                 |
 | typescript  | boolean                                | 是否使用 TS                                  |
 | pageName    | string                                 | `taro create` 时传入的页面名称，默认 'index' |
 | template    | string                                 | 模板名称                                     |
-
+| framework   | 'React' or 'Preact' or 'Vue' or 'Vue3' | 框架名称                                     |
+| compiler    | 'Webpack4' or 'Webpack5' or 'Vite'     | 编译模式名称                                 |
 ##### 例子
 
-```ejs title="index.js"
-<%if (typescript) {-%>
-import Taro, { Component, Config } from '@tarojs/taro'
-<%} else { -%>
-import Taro, { Component } from '@tarojs/taro'
-<%}-%>
-import { View, Text } from '@tarojs/components'
-import './<%= pageName %>.<%= cssExt %>'
+```handlebars
+import { defineConfig{{#if typescript }}, type UserConfigExport{{/if}} } from '@tarojs/cli'
+{{#if typescript }}import TsconfigPathsPlugin from 'tsconfig-paths-webpack-plugin'{{/if}}
 ```
 
 #### handler 字段
@@ -155,6 +166,12 @@ handler 用于控制是否生成某文件，或给文件传入特定参数。
 
 params: object
 
+:::info
+`params.pageDir` Taro v4.0.0+ 开始支持
+
+`params.subPkg` Taro v4.0.0+ 开始支持
+:::
+
 | 属性         | 类型                                   | 说明                                          |
 | :----------- | :------------------------------------- | :-------------------------------------------- |
 | projectName  | string                                 | 项目名                                        |
@@ -164,13 +181,19 @@ params: object
 | css          | 'none' or 'sass' or 'stylus' or 'less' | 样式预处理工具                                |
 | typescript   | boolean                                | 是否使用 TS                                   |
 | pageName     | string                                 | 页面名称                                      |
+| pageDir      | string                                 | 页面路径（相对于「页面目录」的相对路径） taro create 时 --dir 传入的值|
+| subPkg       | string                                 | 分包页面路径（相对于「src目录」的相对路径） taro create 时 --subpkg 传入的值|
 | template     | string                                 | 模板名称                                      |
 | templatePath | string                                 | 模板路径                                      |
 | projectPath  | string                                 | 目标路径                                      |
 | period       | 'createApp' or 'createPage'            | `taro init` 创建项目或 `taro create` 创建页面 |
 
 return: boolean/object
 
+:::info
+`object.setSubPkgName` Taro v4.0.0+ 开始支持
+:::
+
 返回值说明
 
 | 取值   | 说明                                                     |
@@ -191,7 +214,7 @@ return: boolean/object
 当用户选择了使用 typescript 时，才生成 **global.d.ts** 和 **tsconfig.json** 文件。
 
 ```js title="template_creator.js"
-function createWhenTs(params) {
+function createWhenTs(err, params) {
   return params.typescript ? true : false
 }
 
@@ -214,12 +237,24 @@ basePageFiles 告诉 CLI，当用户使用 `taro create` 命令创建页面时
 当用户使用命令 `taro create --page=detail` 时，会创建 **/src/pages/detail/detail.jsx** 与 **/src/pages/detail/detail.css** 两个文件。
 
 ```js title="template_creator.js"
+const path = require('path')
+
+function normalizePath (path) {
+  return path.replace(/\\/g, '/').replace(/\/{2,}/g, '/')
+}
+
 const handler = {
-  '/src/pages/index/index.jsx'({ pageName }) {
-    return { setPageName: `/src/pages/${pageName}/${pageName}.jsx` }
+  '/src/pages/index/index.jsx' (err, { pageName = '', pageDir = '', subPkg = '' }) {
+    return {
+      setPageName: normalizePath(path.join(PAGES_ENTRY, pageDir, pageName, 'index.jsx')),
+      setSubPkgName: normalizePath(path.join(SOURCE_ENTRY, subPkg, pageDir, pageName, 'index.jsx'))
+    }
   },
-  '/src/pages/index/index.css'({ pageName }) {
-    return { setPageName: `/src/pages/${pageName}/${pageName}.css` }
+  '/src/pages/index/index.css' (err, { pageName = '', pageDir = '', subPkg = '' }) {
+    return {
+      setPageName: normalizePath(path.join(PAGES_ENTRY, pageDir, pageName, 'index.css')),
+      setSubPkgName: normalizePath(path.join(SOURCE_ENTRY, subPkg, pageDir, pageName, 'index.css'))
+    }
   },
 }
 
@@ -230,3 +265,11 @@ module.exports = {
   basePageFiles,
 }
 ```
+
+### compiler 字段
+
+:::info
+Taro v4.0.0+ 开始支持
+:::
+
+compiler 告诉 cli 当前模版支持的编译器类型，该值是一个 `string[]`，目前 taro 支持的编译器类型有 `Webpack4、Webpack5、Vite`

versioned_docs/version-4.x/cli.md

@@ -62,9 +62,24 @@ Taro Doctor 就像一个医生一样，可以诊断项目的依赖、设置、
 
 ### 快速创建新页面
 
-Taro create --name [页面名称] 能够在当前项目的 pages 目录下快速生成新的页面文件，并填充基础代码，是一个提高开发效率的利器。
+Taro create --name [页面名称] --dir [路径] --subpkg [分包路径]  能够在当前项目的指定目录下快速生成新的页面文件，并填充基础代码，是一个提高开发效率的利器。
 
-> taro 会尝试同步修改 `app.config.js` 配置文件中的 `pages` 字段。
+> taro 会尝试同步修改 `app.config.js` 配置文件中的 `pages` 或者 `subPackages` 字段。
+
+#### 例子
+假设当前当前跟路径为 `/project/root`。
+
+执行下面命令创建主包页面：
+```bash
+taro create newPage --dir pages/mydir
+```
+那么会在 `/project/root/src/pages/mydir` 目录下生成新的页面，并且在 `app.config.js` 中自动补齐 `pages` 字段。
+
+执行下面命令创建分包页面：
+```bash
+taro create newPage --subpkg mysubpages
+```
+那么会在 `/project/root/src/mysubpages` 目录下生成新的页面，并且在 `app.config.js` 中自动补齐 `subPackages` 字段。
 
 ### 快速创建插件模版