README.zh.md

hero-cli

Documetation for English

用来快速构建Hero App的命令行工具

• 快速开始 – 如何使用hero-cli工具快速创建一个Hero App
• 使用文档 – 如何使用hero-cli工具帮助开发一个Hero App

Hero App可以运行在Android, iOS和高级浏览器等环境中。如果发现任何issue，可以点击这里告诉我们。

如何构建Hero App

运行以下命令

npm install -g hero-mobile/hero-cli

hero init my-app
cd my-app/

npm install

当相关依赖安装完成后，在项目更目录下，可以运行以下命令：

• npm start 启动Hero App服务
• npm run build 将项目代码打包，生成一份优化后的代码，用于部署
• npm run android 生成一个Android APK格式的安装文件

成功运行npm start后，打开链接http://localhost:3000/index.html可看到如下界面：

hero-cli使用Webpack来进行项目的打包，相应的配置隐藏在工具内部，让开放者更关注与业务逻辑的开发。

快速开始

安装

运行以下命令进行全局安装，安装后可以使用hero命令

npm install -g hero-mobile/hero-cli

Node版本需要高于4.0，建议使用Node >= 6 和 npm >= 3 你可以使用nvm来安装，管理多个Node版本，并可以方便地在各个版本间进行切换。

创建Hero App

使用hero init命令来初始化一个Hero App

hero init my-app
cd my-app

该命令会在当前目录下创建一个my-app的目录并生成相应的项目代码，目录结构如下：

├── environments
│   ├── environment-dev.js
│   └── environment-prod.js
├── platforms
│   ├── android
│   └── iOS
├── public
│   ├── ...
│   └── favicon.ico
├── src
│   ├── ...
│   ├── index.html
│   └── index.js
├── .babelrc
├── .editorconfig
├── .eslintrc
├── .gitattributes
├── .gitignore
├── .hero-cli.json
├── package.json
└── README.md

在初始化的项目代码中, 以下文件或目录必须存在:

• platforms 存放Android/iOS原生代码
• src/index.html 项目的HTML入口文件;
• src/index.js 项目的JavaScript入口文件.
• .hero-cli.json Hero App的配置文件。比如当用户运行npm start或npm run build（实际上在package.json中配置的调用的命令为hero start -e dev 和hero build -e prod）时，该加载哪些配置项。了解更多部署构建选项，点击查看构建命令.

其他：

• public 该目录可以用来存放一个通用的资源，这些资源不会经过Webpack处理，而是直接复制到打包后的文件中
• src 该目录存放的文件会被Webpack处理，可以把JS,CSS等文件放在这个目录
• environments 存放不同环境的配置文件(该目录的路径可以在文件.hero-cli.json中配置)，该配置文件中的值可以通过全局变量访问到。具体方法见添加环境变量.

你也许会发现HTML文件pages/start.html不存在，没错，该文件是生成出来的。详情见动态生成HTML

使用文档

• 动态生成HTML
• 添加环境变量
  • JavaScript文件中引用环境变量
  • HTML文件中引用环境变量
  • Shell命令中添加环境变量
  • .hero-cli.json文件中添加环境变量
• 请求代理服务
• 构建原生App安装包
  • Android
  • iOS
• 构建命令
  • hero start
  • hero build
  • hero serve
  • hero init
  • hero platform build android

动态生成HTML

在src目录中的JS文件，如果满足以下２个条件

• JS文件中存在class的类声明
• 声明的class类被来自hero-cli/decorator的Decorator @Entry所修饰

则会经Webpack插件html-webpack-plugin生成相应的HTML文件

• 可以通过@Entry(options)指定HTML文件生成的选项
• 默认情况下，该HTML文件生成后，访问的路径与当前JS的路径结构一致，你可以通过属性path来自定HTML访问的路径
• 生成的HTML文件也可以访问环境变量。如何添加环境变量？点击查看添加环境变量。

示例:

文件src/pages/start.js将会生成一个对应的HTML文件，该HTML文件的访问路径为/pages/start.html, 同时该HTML文件包含了对src/pages/start.js的引用。

这就是为什么我们可以访问HTMLhttp://localhost:3000/pages/start.html.

// 文件：
import { Entry } from 'hero-cli/decorator';

// 被@Entry所修饰的class，会生成一个对应的HTML文件
// 当前JS路径为: src/pages/start.js
// 所以生成的HTML访问路径为 /pages/start.html
//
// 代码＠Entry()
// 效果同
// @Entry({
//   path: '/pages/start.html'
// })
//
@Entry()
export class DecoratePage {

    sayHello(data){
      console.log('Hello Hero!')
    }

}

添加环境变量

项目代码可以访问机器上的环境变量。默认情况下，可以访问所有以HERO_APP_开头的变量，这样做的好处是，这些变量可以脱离版本管理工具如Git, SVN的控制。

环境变量是在构建过程中添加进去的.

JavaScript文件中引用环境变量

在JavaScript文件中，可以通过全局变量process.env来访问环境变量，例如，当存在一个名为HERO_APP_SECRET_CODE的环境变量，则可以在JS中使用process.env.HERO_APP_SECRET_CODE来访问。

console.log('Send Request with Token: '+ process.env.HERO_APP_SECRET_CODE);

同时，hero-cli会内置额外的２个环境变量NODE_ENV和HOME_PAGE到process.env中。

当运行hero start时，NODE_ENV的值为'development'；当运行hero build时，NODE_ENV的值为'production'；你不可以改变它的值，这是为了防止开发着误操作，将开发环境的包部署至生产。

使用NODE_ENV可以方便的执行某些操作：

例如：根据当前环境确定是否需要进行数据统计

if (process.env.NODE_ENV !== 'production') {
  analytics.disable();
}

你可以访问HOME_PAGE，该变量的至为用户在.hero-cli.json中配置的homepage属性的值，它表示当前页面部署的URL路径。参考构建路径配置.

HTML文件中引用环境变量

在HTML文件中，可以是用如下格式访问：

实例：当存在值为Welcome Hero的环境变量HERO_APP_WEBSITE_NAME，

<title>%HERO_APP_WEBSITE_NAME%</title>

当用户访问该HTML文件时，标题<title>的值为Welcome Hero:

<title>Welcome Hero</title>

Shell命令中添加环境变量

可以在Shell命令中添加环境变量，不同操作系统的声明方式不同。

Windows (cmd.exe)

set HERO_APP_SECRET_CODE=abcdef&&npm start

Linux, macOS (Bash)

HERO_APP_SECRET_CODE=abcdef npm start

.hero-cli.json文件中添加环境变量

部署阶段，环境变量会随着部署环境的不同而不同，如开发环境, 测试环境和生产环境等。你可以通过在文件.hero-cli.json中指定相应环境及环境变量的对应关系。

示例：

以下是文件.hero-cli.json的内容，指定了dev和prod环境及环境变量的对应关系

{
  "environments": {
    "dev": "src/environments/environment-dev.js",
    "prod": "src/environments/environment-prod.js"
  }
}

以下是文件src/environments/environment-prod.js的内容

var environment = {
    backendURL: 'http://www.my-website.com/api'
};

module.exports = environment;

当运行命令hero start -e dev或hero build -e dev时，文件src/environments/environment-dev.js中定义的变量在JavaScript中可以通过process.env访问。

请求代理服务

项目部署阶段，运维人员经常会把前后端部署在同一域名和端口下，从而避免跨域问题。

例如，项目部署后，前后的的访问情况如下：

/             - 可以访问前端的静态资源，如index.html
/api/todos    - URL匹配/api/*的请求，能访问后端的服务API接口

这样的线上配置并不是必须的，不过这样配置后，可以使用类似fetch('/api/v2/todos')的代码来发起后端服务请求。

然而在开发过程中，前端服务与后端服务通常在不同的端口，会出现跨域的问题。为了解决该问题，可以透明地将请求转发至相应的后端服务，从而解决跨域问题。

可以通过配置文件.hero-cli.json，实现请求代理服务。

实例：以下是文件.hero-cli.json内容

{
  "proxy": {
    "/api/v2": "https://localhost:4000",
    "/feapi": "https://localhost:4001",
  },
  "environments": {
    "dev": "src/environments/environment-dev.js",
    "prod": "src/environments/environment-prod.js"
  }
}

这样配置之后，当代码fetch('/api/v2/todos')发送请求时，该请求会被转发至https://localhost:4000/api/v2/todos；当代码fetch('/feapi/todos')发送请求时，该请求会被转发至https://localhost:4001/feapi/todos.

构建原生App安装包

Android

Prerequisites

• Java
• Android SDK
• Gradle

配置环境变量

• JAVA_HOME
• ANDROID_HOME
• GRADLE_HOME

当安装使用该工具生成后的App，在启动时会加载一个入口文件，该入口文件包含相应的业务逻辑代码。

因此，在生成该App的安装包时，需要进行以下步骤：

• 使用hero build命令将业务逻辑代码打包部署
• 在文件.hero-cli.json中指定一个HTML入口地址
• 使用[hero platform build](#hero- platform-build)命令生成App安装包，同时需使用-e参数指定使用哪个配置文件

示例：　

以下是文件.hero-cli.json的内容

{
  "android": {
    "prod": {
      "host": "http://www.my-site.com:3000/mkt/pages/start.html"
    }
  }
}

接着运行以下命令便可生成Android APK安装文件：

hero platform build android -e prod

该APK文件生成的路径为： platforms/android/app/build/outputs/apk.

查看更多信息，点击查看构建Android APK安装包

iOS

构建命令

以下构建命令可以添加--verbose参数输出详细日志。

hero start

该命令会启动开发环境的模式，你可以运行hero start -h查看帮助。 该命令需要一个-e参数，指定启动时的配置文件。用法为: hero start -e <env>。

-e参数的值是根据文件.hero-cli.json中属性environments来确定的。用法在这里有说明

同时，可以使用-p参数指定服务启动的端口。

hero start -e dev -p 3000

启动成功后，队友src目录中的改动，代码都会重新编译并且浏览器会重新刷新页面，对有JavaScript代码的ESLint结果会显示在浏览器的控制台中。

更多选项

• -e
  指定在启动时加载的配置环境的名称
• -s
  指定打包后的文件中只包含业务逻辑代码，不包括webcomponent polyfills 和hero-js等组件库。
• -i
  指定将JavaScript和CSS内联至HTML文件中。
• -b
  指定打包后的文件中只包含webcomponent polyfills 和hero-js等组件库。
• -m
  不生成sourcemap文件。默认生成sourcemap文件。
• -f
  指定生成AppCache文件，默认的文件名称为"app.appcache"。默认情况下不生成该文件。
• -n
  指定文件名保留原始名称，不添加hash值。默认是添加hash值。

hero build

使用该命令可以对项目进行打包构建，该命令也需要指定一个必需的参数-e，相关的参数同hero start。 你可以运行hero build -h查看帮助。

构建路径配置

默认情况下，hero-cli会认为该项目打包构建后生成的文件，在这些文件中，互相引用的路径为绝对路径，并且部署在域名的根路径之下。 当需要修改该情况，可以通过修改文件.hero-cli.json中属性　homepage 的值。

示例：

以下是文件.hero-cli.json的内容

{
  "environments": {
    "dev": "src/environments/environment-dev.js",
    "prod": "src/environments/environment-prod.js"
  },
  "homepage": "/mkt/"
}

这样配置之后，资源在访问是需要加上前缀/mkt,比如原先的/start.html路径变为/mkt/pages/start.html。

hero serve

打使用hero build命令打包完成后，在部署之前，可以使用该命令预览构建后的代码运行后的效果。

hero init

使用该命令可以初始化一个Hero App项目工程。示例用法见如何构建Hero App.

hero platform build

This command used for build native app. And you can run hero platform build -h for help.

构建Android APK安装包

hero platform build android

该命令需要指定一个必需的参数-e <env>，其中<env>的取值根据文件.hero-cli.json中属性android来确定。

示例： 以下是文件.hero-cli.json的内容

{
  "android": {
    "dev": {
      "host": "http://10.0.2.2:3000/mkt/pages/start.html"
    },
    "prod": {
      "host": "http://www.my-site.com:3000/mkt/pages/start.html"
    }
  }
}

那么可选的env参数则有dev和prod。

当安装并打开该Native App时，启动时则会加载页面http://www.my-site.com:3000/mkt/pages/start.html。

How to specify the android build tool version in SDK

hero-cli会自动检测当前开发者环境已安装的Android build tool的所有可用版本，并会默认使用最新的版本。 当然，你也可以手动的指定在打包时需要使用的各个版本。方法是在命令hero platform build android中指定各个版本，不同工具的版本使用分号分割。

示例：

指定ANDROID_HOME/build-toos的版本为23.0.2，同时指定com.android.support:appcompat-v7的版本为24.0.0-alpha1，其命令格式如下

hero platform build android:23.0.2:24.0.0-alpha1 -e prod

或者只指定ANDROID_HOME/build-toos为23.0.2，则其命令格式如下：

hero platform build android:23.0.2 -e prod