Home

Awesome

npm version Circle CI

DISCLAIMER: NO LONGER MAINTAINED

Oh, hello there! Ionic App Scripts is a tool tied specifically to version 3.x of Ionic Framework. Since the release of version 4.0 of Ionic Framework, we are no longer using Ionic App Scripts for building in Ionic Framework. Version 3 of Ionic Framework is no longer actively maintained by us. For more information on which versions are active, see our support policy. Due to this, we are no longer maintaining Ionic App Scripts and we recommend developers update their apps to the latest framework release. This provides several new features, bug fixes, performance improvements, as well as up to date tooling for Ionic apps. For more details on how to upgrade, check out our migration guide.

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:

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

Environments

You can use Node style process.env.MY_VAR syntax directly in your typescript and when the application is bundled it'll be replaced with the following order of precedence:

In order to take advantage of this apps will need a src/declarations.d.ts file with the following declaration:

declare var process: { env: { [key: string]: string | undefined; } };

Note: This declaration may conflict if @types/node is installed in your project. See #3541.

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 Filepackage.json ConfigCmd-line Flag
CleanCssionic_cleancss--cleancss or -e
Copyionic_copy--copy or -y
Generatorionic_generator--generator or -g
NGCionic_ngc--ngc or -n
Sassionic_sass--sass or -s
TSLintionic_tslint--tslint or -i
UglifyJSionic_uglifyjs--uglifyjs or -u
Watchionic_watch--watch
Webpackionic_webpack--webpack or -w

Overriding Config Values

Config Valuespackage.json ConfigCmd-line FlagDefaultsDetails
root directoryionic_root_dir--rootDirprocess.cwd()The directory path of the Ionic app
src directoryionic_src_dir--srcDirsrcThe directory holding the Ionic src code
www directoryionic_www_dir--wwwDirwwwThe deployable directory containing everything needed to run the app
build directoryionic_build_dir--buildDirbuildThe build process uses this directory to store generated files, etc
temp directoryionic_tmp_dir--tmpDir.tmpTemporary directory for writing files for debugging and various build tasks
ionic-angular directoryionic_angular_dir--ionicAngularDirionic-angularionic-angular directory
ionic-angular entry pointionic_angular_entry_point--ionicAngularEntryPointindex.jsentry point file for ionic-angular
source map typeionic_source_map_type--sourceMapTypesource-mapChooses the webpack devtool option. eval and source-map are supported
generate source mapionic_generate_source_map--generateSourceMaptrueDetermines whether to generate a source map or not
tsconfig pathionic_ts_config--tsconfig{{rootDir}}/tsconfig.jsonabsolute path to tsconfig.json
app entry pointionic_app_entry_point--appEntryPoint{{srcDir}}/app/main.tsabsolute path to app's entrypoint bootstrap file
app ng module pathionic_app_ng_module_path--appNgModulePath{{srcDir}}/app/app.module.tsabsolute path to app's primary NgModule
app ng module classionic_app_ng_module_class--appNgModuleClassAppModuleExported class name for app's primary NgModule
clean before copyionic_clean_before_copy--cleanBeforeCopyfalseclean out existing files before copy task runs
output js fileionic_output_js_file_name--outputJsFileNamemain.jsname of js file generated in buildDir
output css fileionic_output_css_file_name--outputCssFileNamemain.cssname of css file generated in buildDir
bail on lint errorionic_bail_on_lint_error--bailOnLintErrornullSet to true to make stand-alone lint commands fail with non-zero status code
enable type checking during lintionic_type_check_on_lint--typeCheckOnLintnullSet to true to enable type checking during lint
write AoT files to diskionic_aot_write_to_disk--aotWriteToDisknullSet to true to write files to disk for debugging
print webpack dependency treeionic_print_webpack_dependency_tree--printWebpackDependencyTreenullSet to true to print out a dependency tree after running Webpack
parse deeplink configionic_parse_deeplinks--parseDeepLinkstrueParses and extracts data from the @IonicPage decorator
convert bundle to ES5ionic_build_to_es5--buildToEs5trueConvert bundle to ES5 for production deployments
default watch timeoutionic_start_watch_timeout--startWatchTimeout3000Milliseconds controlling the default watch timeout
choose the polyfillionic_polyfill_name--polyfillNamepolyfillsChange with polyfills.modern or polyfills.ng (all options)[https://github.com/driftyco/ionic/tree/master/scripts/polyfill]
enable lintingionic_enable_lint--enableLinttrueSet 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 VariableDescription
IONIC_ENVValue can be either prod or dev.
IONIC_ROOT_DIRThe absolute path to the project's root directory.
IONIC_SRC_DIRThe absolute path to the app's source directory.
IONIC_WWW_DIRThe absolute path to the app's public distribution directory.
IONIC_BUILD_DIRThe absolute path to the app's bundled js and css files.
IONIC_TMP_DIRTemp directory for debugging generated/optimized code and various build tasks
IONIC_NODE_MODULES_DIRThe absolute path to the node_modules directory.
IONIC_ANGULAR_DIRThe absolute path to the ionic-angular node_module directory.
IONIC_APP_SCRIPTS_DIRThe absolute path to the @ionic/app-scripts node_module directory.
IONIC_SOURCE_MAP_TYPEThe Webpack devtool setting. eval and source-map are supported.
IONIC_GENERATE_SOURCE_MAPDetermines whether to generate a sourcemap or not.
IONIC_TS_CONFIGThe absolute path to the project's tsconfig.json file
IONIC_APP_ENTRY_POINTThe absolute path to the project's main.ts entry point file
IONIC_APP_NG_MODULE_PATHThe absolute path to app's primary NgModule
IONIC_APP_NG_MODULE_CLASSThe exported class name for app's primary NgModule
IONIC_GLOB_UTILThe path to Ionic's glob-util script. Used within configs.
IONIC_CLEAN_BEFORE_COPYAttempt to clean existing directories before copying files.
IONIC_CLOSURE_JARThe absolute path ot the closure compiler jar file
IONIC_OUTPUT_JS_FILE_NAMEThe file name of the generated javascript file
IONIC_OUTPUT_CSS_FILE_NAMEThe file name of the generated css file
IONIC_WEBPACK_FACTORYThe absolute path to Ionic's webpack-factory script
IONIC_WEBPACK_LOADERThe absolute path to Ionic's custom webpack loader
IONIC_BAIL_ON_LINT_ERRORBoolean determining whether to exit with a non-zero status code on error
IONIC_TYPE_CHECK_ON_LINTBoolean determining whether to type check code during lint or not
IONIC_AOT_WRITE_TO_DISK--aotWriteToDisk
IONIC_PRINT_WEBPACK_DEPENDENCY_TREEboolean to print out a dependency tree after running Webpack
IONIC_PARSE_DEEPLINKSboolean to enable parsing the Ionic 3.x deep links API for lazy loading
IONIC_BUILD_TO_ES5boolean to enable converting bundle to ES5 for production deployments
IONIC_START_WATCH_TIMEOUTMilliseconds 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.

TaskDescription
buildA complete build of the application. It uses development settings by default. Use --prod to create an optimized build
cleanEmpty the www/build directory.
cleancssCompress the output CSS with CleanCss
copyRun the copy tasks, which by defaults copies the src/assets/ and src/index.html files to www.
lintRun the linter against the source .ts files, using the tslint.json config file at the root.
minifyMinifies the output JS bundle and compresses the compiled CSS.
sassSass compilation of used modules. Bundling must have at least ran once before Sass compilation.
watchRuns watch for dev builds.

Example NPM Script:

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

Tips

  1. 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.
  2. 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 Nightly Build

  1. Run npm run build to generate the dist directory
  2. Run npm run test to validate the dist works
  3. Tick the package.json version
  4. Run npm run nightly to generate a nightly build on npm

Publish a release

Execute the following steps to publish a release:

  1. Ensure your branch has been merged into master
  2. Run npm run build to generate the dist directory
  3. Run npm run test to validate the dist works
  4. Temporarily tick the package.json version
  5. Run npm run changelog to append the latest additions to the changelog
  6. Manually verify and commit the changelog changes. Often times you'll want to manually add content/instructions
  7. Revert the package.json version to the original version
  8. Run npm version patch to tick the version and generate a git tag
  9. Run npm run github-release to create the github release entry
  10. Run npm publish to publish the package to npm
  11. git push origin master - push changes to master