Ionic App Scripts

Helper scripts to get Ionic apps up and running quickly (minus the config overload).

To get the latest @ionic/app-scripts, please run:

npm install @ionic/app-scripts@latest --save-dev

Config Defaults

Out of the box, Ionic starters have been preconfigured with great defaults for building fast apps, including:

Multi-core processing tasks in parallel for faster builds
In-memory file transpiling and bundling
Transpiling source code to ES5 JavaScript
Ahead of Time (AoT) template compiling
Just in Time (JiT) template compiling
Template inlining for JiT builds
Bundling modules for faster runtime execution
Treeshaking unused components and dead-code removal
Generating CSS from bundled component Sass files
Autoprefixing vendor CSS prefixes
Minifying JavaScript files
Compressing CSS files
Copying src static assets to www
Linting source files
Watching source files for live-reloading

Just the bullet list above is a little overwhelming, and each task requires quite a bit of development time just to get started. Ionic App Script's intention is to make it easier to complete common tasks so developers can focus on building their app, rather than building build scripts.

Note that the Ionic Framework's source is made up of modules and can be packaged by any bundler or build process. However, this project's goal is provide simple scripts to make building Ionic apps easier, while also allowing developers to further configure their build process.

npm Scripts

Instead of depending on external task runners, Ionic App Scripts now prefers being executed from npm scripts. Ionic's npm scripts come preconfigured in the project's package.json file. For example, this is the default setup for npm scripts in each starter:

  "scripts": {
    "ionic:build": "ionic-app-scripts build",
    "ionic:serve": "ionic-app-scripts serve"
  },

To run the build script found in the package.json scripts property, execute:

npm run build

Custom Configuration

In many cases, the defaults which Ionic provides cover most of the scenarios required by developers; however, Ionic App Scripts does provide multiple ways to configure and override the defaults for each of the various tasks. Note that Ionic will always apply its defaults for any property that was not provided by custom configuration.

Default Config Files

package.json Config

Ionic projects use the package.json file for configuration. There's a handy config property which can be used. Below is an example of setting a custom config file using the config property in a project's package.json.

  "config": {
    "ionic_cleancss": "./config/cleancss.config.js"
  },

Command-line Flags

Remember how we're actually running ionic-app-scripts from the scripts property of a project's package.json file? Well we can also add command-line flags to each script, or make new scripts with these custom flags. For example:

  "scripts": {
    "build": "ionic-app-scripts build --webpack ./config/webpack.dev.config.js",
    "minify": "ionic-app-scripts minify --cleancss ./config/cleancss.config.js",
  },

The same command-line flags can be also applied to npm run commands too, such as:

npm run build --webpack ./config/webpack.dev.config.js

Overriding Config Files

Config File	package.json Config	Cmd-line Flag
CleanCss	`ionic_cleancss`	`--cleancss` or `-e`
Copy	`ionic_copy`	`--copy` or `-y`
Generator	`ionic_generator`	`--generator` or `-g`
NGC	`ionic_ngc`	`--ngc` or `-n`
Sass	`ionic_sass`	`--sass` or `-s`
TSLint	`ionic_tslint`	`--tslint` or `-i`
UglifyJS	`ionic_uglifyjs`	`--uglifyjs` or `-u`
Watch	`ionic_watch`	`--watch`
Webpack	`ionic_webpack`	`--webpack` or `-w`

Overriding Config Values

Config Values	package.json Config	Cmd-line Flag	Defaults	Details
root directory	`ionic_root_dir`	`--rootDir`	`process.cwd()`	The directory path of the Ionic app
src directory	`ionic_src_dir`	`--srcDir`	`src`	The directory holding the Ionic src code
www directory	`ionic_www_dir`	`--wwwDir`	`www`	The deployable directory containing everything needed to run the app
build directory	`ionic_build_dir`	`--buildDir`	`build`	The build process uses this directory to store generated files, etc
temp directory	`ionic_tmp_dir`	`--tmpDir`	`.tmp`	Temporary directory for writing files for debugging and various build tasks
ionic-angular directory	`ionic_angular_dir`	`--ionicAngularDir`	`ionic-angular`	ionic-angular directory
ionic-angular entry point	`ionic_angular_entry_point`	`--ionicAngularEntryPoint`	`index.js`	entry point file for ionic-angular
source map type	`ionic_source_map_type`	`--sourceMapType`	`source-map`	Chooses the webpack `devtool` option. `eval` and `source-map` are supported
generate source map	`ionic_generate_source_map`	`--generateSourceMap`	`true`	Determines whether to generate a source map or not
tsconfig path	`ionic_ts_config`	`--tsconfig`	`{{rootDir}}/tsconfig.json`	absolute path to tsconfig.json
app entry point	`ionic_app_entry_point`	`--appEntryPoint`	`{{srcDir}}/app/main.ts`	absolute path to app's entrypoint bootstrap file
app ng module path	`ionic_app_ng_module_path`	`--appNgModulePath`	`{{srcDir}}/app/app.module.ts`	absolute path to app's primary `NgModule`
app ng module class	`ionic_app_ng_module_class`	`--appNgModuleClass`	`AppModule`	Exported class name for app's primary `NgModule`
clean before copy	`ionic_clean_before_copy`	`--cleanBeforeCopy`	`false`	clean out existing files before copy task runs
output js file	`ionic_output_js_file_name`	`--outputJsFileName`	`main.js`	name of js file generated in `buildDir`
output css file	`ionic_output_css_file_name`	`--outputCssFileName`	`main.css`	name of css file generated in `buildDir`
bail on lint error	`ionic_bail_on_lint_error`	`--bailOnLintError`	`null`	Set to `true` to make stand-alone lint commands fail with non-zero status code
enable type checking during lint	`ionic_type_check_on_lint`	`--typeCheckOnLint`	`null`	Set to `true` to enable type checking during lint
write AoT files to disk	`ionic_aot_write_to_disk`	`--aotWriteToDisk`	`null`	Set to `true` to write files to disk for debugging
print webpack dependency tree	`ionic_print_webpack_dependency_tree`	`--printWebpackDependencyTree`	`null`	Set to `true` to print out a dependency tree after running Webpack
parse deeplink config	`ionic_parse_deeplinks`	`--parseDeepLinks`	`true`	Parses and extracts data from the `@IonicPage` decorator
convert bundle to ES5	`ionic_build_to_es5`	`--buildToEs5`	`true`	Convert bundle to ES5 for production deployments
default watch timeout	`ionic_start_watch_timeout`	`--startWatchTimeout`	`3000`	Milliseconds controlling the default watch timeout
choose the polyfill	`ionic_polyfill_name`	`--polyfillName`	`polyfills`	Change with polyfills.modern or polyfills.ng (all options)[https://github.com/driftyco/ionic/tree/master/scripts/polyfill]
enable linting	`ionic_enable_lint`	`--enableLint`	`true`	Set to `false` for skipping the linting after the build

Ionic Environment Variables

These environment variables are automatically set to Node's process.env property. These variables can be useful from within custom configuration files, such as custom webpack.config.js file.

Environment Variable	Description
`IONIC_ENV`	Value can be either `prod` or `dev`.
`IONIC_ROOT_DIR`	The absolute path to the project's root directory.
`IONIC_SRC_DIR`	The absolute path to the app's source directory.
`IONIC_WWW_DIR`	The absolute path to the app's public distribution directory.
`IONIC_BUILD_DIR`	The absolute path to the app's bundled js and css files.
`IONIC_TMP_DIR`	Temp directory for debugging generated/optimized code and various build tasks
`IONIC_NODE_MODULES_DIR`	The absolute path to the `node_modules` directory.
`IONIC_ANGULAR_DIR`	The absolute path to the `ionic-angular` node_module directory.
`IONIC_APP_SCRIPTS_DIR`	The absolute path to the `@ionic/app-scripts` node_module directory.
`IONIC_SOURCE_MAP_TYPE`	The Webpack `devtool` setting. `eval` and `source-map` are supported.
`IONIC_GENERATE_SOURCE_MAP`	Determines whether to generate a sourcemap or not.
`IONIC_TS_CONFIG`	The absolute path to the project's `tsconfig.json` file
`IONIC_APP_ENTRY_POINT`	The absolute path to the project's `main.ts` entry point file
`IONIC_APP_NG_MODULE_PATH`	The absolute path to app's primary `NgModule`
`IONIC_APP_NG_MODULE_CLASS`	The exported class name for app's primary `NgModule`
`IONIC_GLOB_UTIL`	The path to Ionic's `glob-util` script. Used within configs.
`IONIC_CLEAN_BEFORE_COPY`	Attempt to clean existing directories before copying files.
`IONIC_CLOSURE_JAR`	The absolute path ot the closure compiler jar file
`IONIC_OUTPUT_JS_FILE_NAME`	The file name of the generated javascript file
`IONIC_OUTPUT_CSS_FILE_NAME`	The file name of the generated css file
`IONIC_WEBPACK_FACTORY`	The absolute path to Ionic's `webpack-factory` script
`IONIC_WEBPACK_LOADER`	The absolute path to Ionic's custom webpack loader
`IONIC_BAIL_ON_LINT_ERROR`	Boolean determining whether to exit with a non-zero status code on error
`IONIC_TYPE_CHECK_ON_LINT`	Boolean determining whether to type check code during lint or not
`IONIC_AOT_WRITE_TO_DISK`	`--aotWriteToDisk`
`IONIC_PRINT_WEBPACK_DEPENDENCY_TREE`	boolean to print out a dependency tree after running Webpack
`IONIC_PARSE_DEEPLINKS`	boolean to enable parsing the Ionic 3.x deep links API for lazy loading
`IONIC_BUILD_TO_ES5`	boolean to enable converting bundle to ES5 for production deployments
`IONIC_START_WATCH_TIMEOUT`	Milliseconds controlling the default watch timeout

The process.env.IONIC_ENV environment variable can be used to test whether it is a prod or dev build, which automatically gets set by any command. By default the build and serve tasks produce dev builds (a build that does not include Ahead of Time (AoT) compilation or minification). To force a prod build you should use the --prod command line flag.

process.env.IONIC_ENV environment variable is set to prod for --prod builds, otherwise dev for all other builds.

All Available Tasks

These tasks are available within ionic-app-scripts and can be added to npm scripts or any Node command.

Task	Description
`build`	A complete build of the application. It uses `development` settings by default. Use `--prod` to create an optimized build
`clean`	Empty the `www/build` directory.
`cleancss`	Compress the output CSS with CleanCss
`copy`	Run the copy tasks, which by defaults copies the `src/assets/` and `src/index.html` files to `www`.
`lint`	Run the linter against the source `.ts` files, using the `tslint.json` config file at the root.
`minify`	Minifies the output JS bundle and compresses the compiled CSS.
`sass`	Sass compilation of used modules. Bundling must have at least ran once before Sass compilation.
`watch`	Runs watch for dev builds.

Example NPM Script:

  "scripts": {
    "minify": "ionic-app-scripts minify"
  },

Tips

The Webpack devtool setting is driven by the ionic_source_map_type variable. It defaults to source-map for the best quality source map. Developers can enable significantly faster builds by setting ionic_source_map_type to eval.
By default, the lint command does not exit with a non-zero status code on error. To enable this, pass --bailOnLintError true to the command.

"scripts" : {
  ...
  "lint": "ionic-app-scripts lint"
  ...
}

npm run lint --bailOnLintError true

The Stack

Contributing

We welcome any PRs, issues, and feedback! Please be respectful and follow the Code of Conduct.

We use Node 6, and NPM 5 for contributing.

Publish a release

Execute the following steps to publish a release:

Run npm run build to generate the dist directory
Run npm run test to validate the dist works
Temporarily tick the package.json version
Run npm run changelog to append the latest additions to the changelog
Manually verify and commit the changelog changes. Often times you'll want to manually add content/instructions
Revert the package.json version to the original version
Run npm version patch to tick the version and generate a git tag
Run npm run github-release to create the github release entry
Run npm publish to publish the package to npm
git push origin master - push changes to master

jjvillavicencio/ionic-app-scripts