Skip to content

Feat/4.x cli vite #243

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Jan 29, 2024
Merged

Feat/4.x cli vite #243

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
b63e2dd
feat: taro-create 相关文档
Jan 29, 2024
460ded4
feat: 编译配置修改
Jan 29, 2024
8990b98
fix: 修复版本错误
Jan 29, 2024
6d11352
feat: 修改配置详情
Jan 29, 2024
f31e7cb
feat: 更新模版
Jan 29, 2024
7177db7
fix: 修复一些错别字
Jan 29, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 17 additions & 2 deletions docs/cli.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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` 字段。

### 快速创建插件模版

Expand Down
46 changes: 36 additions & 10 deletions docs/config-detail.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -609,6 +612,14 @@ webpack 编译过程中的错误类型主要如下两类：1、致命的 wepback

不需要执行预编译的依赖。

### compiler.vitePlugins

> 只有 vite 支持

`array`

vite 插件

## cache

:::info
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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 = {
Expand Down Expand Up @@ -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 的配置。
Expand Down
13 changes: 4 additions & 9 deletions docs/config.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,13 +49,6 @@ const config = {
autoprefixer: {
enable: true,
},
// 小程序端样式引用本地资源内联配置
url: {
enable: true,
config: {
limit: 10240,
},
},
cssModules: {
enable: false, // 默认为 false，如需使用 css modules 功能，则设为 true
config: {
Expand Down Expand Up @@ -102,6 +95,8 @@ module.exports = function (merge) {
:::info
Taro v3.6.9 开始支持

Taro v4.0.0 之后支持范型，可以传入编译器类型 'webpack4 | 'webpack5 | 'vite'

react native 暂不支持
:::

Expand All @@ -113,7 +108,7 @@ react native 暂不支持
// config/index.ts
import { defineConfig } from '@tarojs/cli'

export default defineConfig({
export default defineConfig<T>({
// ...Taro 配置
})
```
Expand All @@ -126,7 +121,7 @@ import type { UserConfigExport } from '@tarojs/cli'

export default {
// ...Taro 配置
} satisfies UserConfigExport
} satisfies UserConfigExport<T>
```

### 异步配置
Expand Down
87 changes: 65 additions & 22 deletions docs/template.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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'))
}
},
}

Expand All @@ -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/) 作为模板语言，各模板文件都将接收到全局模板参数。

##### 默认全局模板参数（模板中可直接使用的变量）

Expand All @@ -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 字段
Expand All @@ -155,6 +166,12 @@ handler 用于控制是否生成某文件，或给文件传入特定参数。

params: object

:::info
`params.pageDir` Taro v4.0.0+ 开始支持

`params.subPkg` Taro v4.0.0+ 开始支持
:::

| 属性 | 类型 | 说明 |
| :----------- | :------------------------------------- | :-------------------------------------------- |
| projectName | string | 项目名 |
Expand All @@ -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+ 开始支持
:::

返回值说明

| 取值 | 说明 |
Expand All @@ -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
}

Expand All @@ -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'))
}
},
}

Expand All @@ -230,3 +265,11 @@ module.exports = {
basePageFiles,
}
```

### compiler 字段

:::info
Taro v4.0.0+ 开始支持
:::

compiler 告诉 cli 当前模版支持的编译器类型，该值是一个 `string[]`，目前 taro 支持的编译器类型有 `Webpack4、Webpack5、Vite`
19 changes: 17 additions & 2 deletions versioned_docs/version-4.x/cli.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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` 字段。

### 快速创建插件模版

Expand Down
Loading