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 build
When you’re ready to deploy to production, create a minified bundle with this command.npm run android
Build the native android apk file.
Run npm start
and then open http://localhost:3000/index.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:
├── 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
For the project to build, these files must exist with exact filenames:
platforms
folder contains Android/iOS codes.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 commandhero start -e dev
orhero build -e prod
(which is invoked bynpm start
ornpm run 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.
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.environments
where your configurations exists(these file path configured in file.hero-cli.json
, you can change it later) and you can access the configuration values in JavaScript or HTML code. See Adding Custom Environment Variables.
You may curious about where is the pages/start.html
. Yes, it's generated by hero-cli. See Generate HTML
User Guide
- Generate HTML
- Adding Custom Environment Variables
- Proxying API Requests in Development
- Build Native App
- Build Scripts
Generate HTML
Any JS file meet the following 2 conditions will treat as JavaScript entry point.
- Declaration of
class
exists in the JS file. class
marked by Decorator@Entry
from hero-cli/decorator.
Which would cause a HTML file generated using Webpack plugin html-webpack-plugin:
- You can specify options during generate HTML via
@Entry(options)
. - Destination of generated HTML file will keep the file path structure of the Javascript entry, or you can override it using the option
path
. - Generated HTML file can access the Custom Environment Variables.
Example:
Below JavaScript file src/pages/start.js
will generate a HTML file access by URL /pages/start.html
, that's why we can visit http://localhost:3000/pages/start.html.
// content of file: src/pages/start.js
import { Entry } from 'hero-cli/decorator';
// class marked by @Entry
// will generate HTML accessed by URL /pages/start.html
// Equal to
// @Entry({
// path: '/pages/start.html'
// })
//
@Entry()
export class DecoratePage {
sayHello(data){
console.log('Hello Hero!')
}
}
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 exist two special built-in environment variable called NODE_ENV
and HOME_PAGE
.
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();
}
You can read variable process.env.HOME_PAGE
, which value is equal to attribute homepage
in file .hero-cli.json
. This is useful for Building for Relative Paths.
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)
HERO_APP_SECRET_CODE=abcdef npm start
.hero-cli.json
Adding Development Environment Variables via Environment variables may varies from environments, such as development
, test
or production
.
You can specify the mapping info in the .hero-cli.json
file, tell hero-cli loads the corresponding variables into 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'
};
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
.
Proxying API Requests in Development
People often serve the front-end appplication from the same host and port as their backend implementation. For example, a production setup might look like this after the app is deployed:
/ - static server returns index.html with application
/api/todos - server handles any /api/* requests using the backend implementation
Such setup is not required. However, if you do have a setup like this, it is convenient to write requests like fetch('/api/v2/todos')
without worrying about redirecting them to another host or port during development.
To tell the development server to proxy any unknown requests to your API server in development, add a proxy field to your .hero-cli.json
, for example:
{
"proxy": {
"/api/v2": "https://localhost:4000",
"/feapi": "https://localhost:4001",
},
"environments": {
"dev": "src/environments/environment-dev.js",
"prod": "src/environments/environment-prod.js"
}
}
This way, when you fetch('/api/v2/todos')
in development, the development server will proxy your request to https://localhost:4000/api/v2/todos
, and when you fetch('/feapi/todos')
, the request will proxy to https://localhost:4001/feapi/todos
.
Build Native App
Android
Prerequisites
Configure your system environment variables
JAVA_HOME
ANDROID_HOME
GRADLE_HOME
Currently, generated native app will loads resources hosted by remote server. In order to make the appliation available in the your mobile.
- Firstly, you can using command
hero build
to generate the package which contains the application codes for deploy. - Secondly, specify the entry url in file
.hero-cli.json
when native app startup. - Finally, using command [
hero platform build
](#hero- platform-build) build the native app. before you generate the apk, you should using parameter-e
to tell the apk loads which url when it startup.
For example:
{
"android": {
"prod": {
"host": "http://www.my-site.com:3000/mkt/pages/start.html"
}
}
}
and then run below command to generate the android apk:
hero platform build android -e prod
Once project build successfully, android apk(s) will generated in folder platforms/android/app/build/outputs/apk
.
For more options, see command of Build Scripts: Build Android App
iOS
Build Scripts
Below scripts support option --verbose
to output more details.
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.
You can using -p
specify the listen port start the application.
hero start -e dev -p 3000
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.
More Vaild options
-e
Environment name of the configuration when start the application-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).-i
Inline JavaScript/CSS code into HTML. Default value is [false].-b
Build pakcage only contain dependecies like hero-js or webcomponents, withou code in /src folder. Default value is [false]-m
Build without sourcemap. Default value is [false], will generate sourcemap.-f
Generate AppCache file, default file name is "app.appcache". Default value is [false], will not generate this file.-n
Rename file without hashcode. Default value is [false], cause filename with hashcode.
hero build
Builds the app for production to the build
folder. Options as same as hero start
mentioned above, or 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) .
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 attribute homepage in configuration .hero-cli.json
file. Accept values see Webpack#publicpath.
For example:
Here is the content of .hero-cli.json
{
"environments": {
"dev": "src/environments/environment-dev.js",
"prod": "src/environments/environment-prod.js"
},
"homepage": "/mkt/"
}
Then you can access the start.html
by URL /mkt/pages/start.html
This will let Hero App correctly infer the root path to use in the generated HTML file.
hero serve
After hero build
process completedly, build
folder will generated. You can serve a static server using hero serve
.
hero init
You can run hero build -h
for help. It will generate the initial project structure of Hero App. See Quick Overview.
hero platform build
This command used for build native app. And you can run hero platform build -h
for help.
Build Android App
hero platform build android
It has one mandatory parameter -e <env>
.
The available env
values from properties of attribute android
in file .hero-cli.json
.
For example:
Here is the content of .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"
}
}
}
The available env
values are dev
and prod
.
Once command hero platform build android -e prod
execute successfully, a android apk will generated, when you install and open the app in your mobile, http://www.my-site.com:3000/mkt/pages/start.html
will be the entry page.
How to specify the android build tool version in SDK
Hero will dynamic using the lastest available one from your local install versions by default.
You might have multiple available versions in the Android SDK. You can specify the ANDROID_HOME/build-toos
version and compile com.android.support:appcompat-v7
version following the command hero platform build android
and seperated by colon.
For example, you can using the below command specify the ANDROID_HOME/build-toos
version 23.0.2
and compile com.android.support:appcompat-v7
version 24.0.0-alpha1
:
hero platform build android:23.0.2:24.0.0-alpha1 -e prod
or just specify the ANDROID_HOME/build-toos
version only:
hero platform build android:23.0.2 -e prod