Hero-cli

Create Hero apps with no build configuration.

Getting Started – How to create a new app.
User Guide – How to develop apps bootstrapped with Hero App.

Hero App works on Android, iOS, and Modem browser.
If something doesn’t work please file an issue.

Quick Overview

npm install -g hero-mobile/hero-cli

hero init my-app
cd my-app/

npm install

Once the installation is done, you can run some commands inside the project folder:

npm start Start the application.
npm run mock You can start the mock server during the development.
npm run build When you’re ready to deploy to production, create a minified bundle with this command.

Run npm start and then open http://localhost:3000/?state=http://localhost:3000/entry/login.html to see your app.

Get Started Immediately

Hero-cli using Webpack to build the boudle for deployment while you don't need to install or configure them.
They are preconfigured and hidden so that you can focus on the code. Just create a project, and you’re good to go.

Getting Started

Installation

Install it once globally:

npm install -g hero-mobile/hero-cli

You’ll need to have Node >= 4 on your machine.

We strongly recommend to use Node >= 6 and npm >= 3 for faster installation speed and better disk usage. You can use nvm to easily switch Node versions between different projects.

Creating an App

To create a new app, run:

hero init my-app
cd my-app

It will create a directory called my-app inside the current folder.
Inside that directory, it will generate the initial project structure and then you can run command npm install to install the dependencies manually:

├── mock/
│   └── ...
├── public
│   ├── ...
│   └── favicon.ico
├── src
│   ├── ...
│   ├── environments
│   │   ├── environment-dev.js
│   │   └── environment-prod.js
│   ├── index.html
│   └── index.js
├── .editorconfig
├── .gitattributes
├── .gitignore
├── .hero-cli.json
├── package.json
└── README.md

For the project to build, these files must exist with exact filenames:

src/index.html is the entry page;
src/index.js is the JavaScript entry point.
.hero-cli.json is the configuration file for hero-cli build, it tell hero loads which configuration when you run command hero start -e dev or hero build -e prod(which is invoked by npm start or npm build) according to the value of -e parameter. For more build options please refer to Build Scripts.

You can delete or rename the other files.

mock you can put your mock data here, which is convenient for you during development. See Usage Here.
public assets like images inside this folder will copied into the build folder untouched. It will not be processed by Webpack.
src For faster rebuilds, only files inside this folder are processed by Webpack. You need to put any JS and CSS files inside this folder, or Webpack won’t see them.
src/environments where your configurations exists(this is configured in file .hero-cli.json, you can change it later) and access the configuration in JavaScript or HTML code. See Adding Custom Environment Variables.

You may curious about where is the entry/login.html. Yes, it's generated by Hero-cli. See Generate HTML

User Guide

Generate HTML
Adding Custom Environment Variables
Build Scripts
- hero start
- hero start

Generate HTML

Any JS file meet the following 2 conditions will treat as JavaScript entry point.

Object class or function exists in the JS file.
class or function marked by Decorator @Entry from hero-cli/decorator.

Which would cause a HTML file generated using Webpack plugin html-webpack-plugin:

Options specified in @Entry(options) will passed to html-webpack-plugin transparently.
Destination of generated HTML file will keep the file path structure of the Javascript entry, or you can override it using the options provided by html-webpack-plugin.
Generated HTML file can access the Adding Custom Environment Variables.

Example:
Below JS will generate a HTML file at <build>/entry/login.html, that's why we can visit http://localhost:3000/entry/login.html.

// content of file: src/entry/login.js
import { Entry } from 'hero-cli/decorator';
import { Component, Boot, Message } from 'hero-js';

var defaultUIViews = {

}
// class marked by @Entry
@Entry()
@Component({
  view: defaultUIViews
})
export class DecoratePage {

    @Boot
    bootstrap(data){
      console.log('Bootstrap successfully!')
    }

    @Message('__data.click && __data.click == "login"')
    loginHandler(data) {
      console.log('Send Login Request...')
    }
}

Adding Custom Environment Variables

Your project can consume variables declared in your environment as if they were declared locally in your JS files. By default you will have any environment variables starting with HERO_APP_. These environment variables can be useful for consuming sensitive data that lives outside of version control.

The environment variables are embedded during the build time.

Referencing Environment Variables in the JavaScript

These environment variables will be defined for you on process.env. For example, having an environment variable named HERO_APP_SECRET_CODE will be exposed in your JS as process.env.HERO_APP_SECRET_CODE.

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

There is also a special built-in environment variable called NODE_ENV. You can read it from process.env.NODE_ENV. When you run hero start, it is always equal to 'development', when you run hero build to make a production bundle, it is always equal to 'production'. You cannot override NODE_ENV manually. This prevents developers from accidentally deploying a slow development build to production.

Having access to the NODE_ENV is also useful for performing actions conditionally:

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

Referencing Environment Variables in the HTML

For example, let’s define a variable HERO_APP_WEBSITE_NAME with value Welcome Hero, and you can access it like this:

<title>%HERO_APP_WEBSITE_NAME%</title>

When you load the app in the browser and inspect the <title>, you will see its value set to Welcome Hero:

<title>Welcome Hero</title>

Adding Temporary Environment Variables In Your Shell

Defining environment variables can vary between OSes. It’s also important to know that this manner is temporary for the life of the shell session.

Windows (cmd.exe)

set HERO_APP_SECRET_CODE=abcdef&&npm start

Linux, macOS (Bash)

REACT_APP_SECRET_CODE=abcdef npm start

Adding Development Environment Variables via `.hero-cli.json`

Environment variables may varies from environments, such as development, test or production.
You can specify the mapping info in the .hero-cli.json file to tells Hero-cli loads the corresponding variables as environment variables.

For example:

Here is the content of .hero-cli.json

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

And here is the content of src/environments/environment-prod.js

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

module.exports = environment;

When you run command hero start -e dev or hero build -e dev, all variables from src/environments/environment-dev.js can be accessed via process.env.

Build Scripts

`hero start`

Runs the app in development mode. And you can run hero start -h for help.

This command has one mandatory parameter -e. Usage: hero start -e <env>

The available <env> values come from keys configured in attribute environments in file .hero-cli.json.

Hero-cli will load the corresponding configurations according to the <env> value by rules mentioned above.

When start successfully, the page will reload if you make edits in folder src.
You will see the build errors and lint warnings in the console.

`hero build`

Builds the app for production to the build folder. And you can run hero build -h for help.
The build is minified and the filenames include the hashes.
It correctly bundles Hero App in production mode and optimizes the build for the best performance.

This command has one mandatory parameter -e. Usage: hero build -e <env>

The available <env> values and configurations loading rules as same as [hero start](#hero start) .

And has another two options:

-s
Build the boundle as standalone version, which should run in Native App environment. That's to say, build version without libarary like webcomponent polyfills or hero-js(These libarary is necessary for Hero App run in web browser, not Native App).
-m
Build the boundle without sourcemap

Building for Relative Paths

By default, Hero-cli produces a build assuming your app is hosted at the server root. To override this, specify the value of preserved key __homepage in your configuration file. Accept values see Webpack#publicpath.