Taro's project initialization template

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:

1. Only the most basic  default templates are kept in the CLI, other templates are removed.
2. 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.
3. 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

example

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

example

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.

example

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
}