Project initialization template
All along, when using Taro CLI taro init
commands to create projects, the CLI will provide several built-in templates for developers to choose from. However, many teams have their own unique business scenarios, and the templates that need to be used and maintained are not consistent. Therefore, Taro supports packaging project templates into a capability for developers.
1.3.9
The following modifications were made to the template functionality of the CLI:
- Only the most basic
default
templates are kept in the CLI, other templates are removed. - The CLI will read the template source configuration items from the CLI global configuration , and then pull templates from the template source for developers to choose.
- Developers can use their own templates by modifying the template source .
template source
The template source is the templateSource field of the CLI configuration item , which can be operated with the taro config command.
Default template source
The default template source is the taro-project-templates warehouse, and the original built-in templates are extracted here.
Configure template source
The template source supports two formats, git template source and url template source .
git template source
- GitHub - github:owner/name
- GitLab - gitlab:owner/name
- Direct - direct:url
# 初始化项目时可以使用 --clone 选项指定拉取远程模板时使用git clone
taro init --clone
url template source
A url pointing to a zip package.
Write a template
Template organization format
The template directory organization supports two types, which are single template mode and template group mode .
Single template mode
git
package.json exists in the root directory of the warehouse.
The template name is the warehouse name.
zip package
The zip package is decompressed into a single folder, and the root directory of the folder contains package.json.
The template name is the folder name extracted from the zip package.
Template group mode
git
Like the default template source , several templates are stored in the root directory of the warehouse.
The template name corresponds to all folder names in the root directory.
zip package
The zip package is decompressed into a single folder, which contains several templates.
The template name corresponds to all folder names in the folder.
static template
A static template means a template without logic, and the CLI will traverse the entire template folder and copy the files to the target location one by one.
Dynamic Template
In many cases, it is necessary to add some logic to the template to generate different template content according to different environments.
Developers can add the template_creator.js file in the root directory of the template, and the file exports objects containing the handler and basePageFiles fields:
template_creator.js
function createWhenTs (params) {
return params.typescript ? true : false
}
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.css' ({ pageName}) {
return { setPageName: `/src/pages/${pageName}/${pageName}.css` }
}
}
const basePageFiles = [
'/src/pages/index/index.jsx',
'/src/pages/index/index.css'
]
module.exports = {
handler,
basePageFiles
}
templating language
Please use ejs as the template language, and each template file will receive global template parameters.
Default global template parameters (variables that can be used directly in the template )
variable | type | illustrate |
---|---|---|
projectName | string | Item name |
description | string | project description |
version | string | Taro CLI version |
date | string | Template Creation Timestamp |
css | 'none' or 'sass' or 'stylus' or 'less' | Style Preprocessing Tool |
cssExt | string | style file suffix |
typescript | boolean | Whether to use TS |
pageName | string | taro create The name of the page passed in, the default is 'index' |
template | string | template name |
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 %>'
handler field
handler is used to control whether to generate a file, or to pass specific parameters to the file.
handler: object
Attributes | type | value |
---|---|---|
file path | function | processing function |
The file path starts with "/", representing the root directory of the template folder
Handling function
params: object
Attributes | type | illustrate |
---|---|---|
projectName | string | Item name |
description | string | project description |
version | string | Taro CLI version |
date | string | Template Creation Timestamp |
css | 'none' or 'sass' or 'stylus' or 'less' | Style Preprocessing Tool |
typescript | boolean | Whether to use TS |
pageName | string | page name |
template | string | template name |
templatePath | string | template path |
projectPath | string | Target path |
period | 'createApp' or 'createPage' | taro init Create a project or taro create create a page |
return: boolean/object
Return value description
value | illustrate |
---|---|
true | Create a file |
false | do not create file |
object | Create the file, and the fields of the returned object will be merged into the global template parameters. |
If the return value is object, some of its properties have special effects:
Attributes | type | illustrate |
---|---|---|
setPageName | string | will replace the output path of the current file |
changeExt | boolean | Whether to automatically replace the file suffix |
When the user chooses to use typescript, the global.d.ts and tsconfig.json files are generated.
template_creator.js
function createWhenTs (params) {
return params.typescript ? true : false
}
const handler = {
'/global.d.ts': createWhenTs,
'/tsconfig.json': createWhenTs
}
module.exports = { handler }
basePageFiles field
basePageFiles tells the CLI taro create
to create the following files when a user creates a page with the command.
Combine the handler field to create a new page.
When the user uses the command taro create --page=detail
, two files /src/pages/detail/detail.jsx and /src/pages/detail/detail.css will be created.
template_creator.js
const handler = {
'/src/pages/index/index.jsx' ({ pageName }) {
return { setPageName: `/src/pages/${pageName}/${pageName}.jsx` }
},
'/src/pages/index/index.css' ({ pageName}) {
return { setPageName: `/src/pages/${pageName}/${pageName}.css` }
}
}
const basePageFiles = [
'/src/pages/index/index.jsx',
'/src/pages/index/index.css'
]
module.exports = {
handler,
basePageFiles
}