Scripts for Ionic Projects

Ionic App Scripts

Helper scripts to get Ionic appsup 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 srcstatic 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'ssource 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.jsonfile. 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 buildscript found in the package.jsonscriptsproperty, 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.jsonfile for configuration. There's a handy configproperty which can be used. Below is an example of setting a custom config file using the configproperty in a project's package.json.

"config": {
    "ionic_bundler": "rollup",
    "ionic_source_map": "source-map",
    "ionic_cleancss": "./config/cleancss.config.js"

Command-line Flags

Remember how we're actually running ionic-app-scriptsfrom the scriptsproperty of a project's package.jsonfile? 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 --rollup ./config/rollup.config.js",
    "minify": "ionic-app-scripts minify --cleancss ./config/cleancss.config.js",

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

npm run build --rollup ./config/rollup.config.js

Overriding Config Files

Config Filepackage.json ConfigCmd-line Flag
CleanCssionic_cleancss--cleancssor -e
Copyionic_copy--copyor -y
Generatorionic_generator--generatoror -g
NGCionic_ngc--ngcor -n
Rollupionic_rollup--rollupor -r
Sassionic_sass--sassor -s
TSLintionic_tslint--tslintor -i
UglifyJSionic_uglifyjs--uglifyjsor -u
Webpackionic_webpack--webpackor -w

Overriding Config Values

Config Valuespackage.json ConfigCmd-line FlagDefaultsDetails
bundlerionic_bundler--bundlerwebpackChooses which bundler to use: webpackor rollup
source map typeionic_source_map--sourceMapevalChooses the webpack devtooloption. We only support evalor source-mapfor now
root directoryionic_root_dir--rootDirprocess.cwd()The directory path of the Ionic app
tmp directoryionic_tmp_dir--tmpDir.tmpA temporary directory for codegen'd files using the Angular ngcAoT compiler
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

Ionic Environment Variables

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

Environment VariableDescription
IONIC_ENVValue can be either prodor dev.
IONIC_ROOT_DIRThe absolute path to the project's root directory.
IONIC_TMP_DIRThe absolute path to the project's temporary 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_APP_SCRIPTS_DIRThe absolute path to the @ionic/app-scriptsnode_module directory.
IONIC_SOURCE_MAPThe Webpack devtoolsetting. We recommend evalor source-map.

The process.env.IONIC_ENVenvironment variable can be used to test whether it is a prodor devbuild, which automatically gets set by any command. By default the buildtask is prod, and the watchand servetasks are dev. Additionally, using the --devcommand line flag will force the build to use dev.

Please take a look at the bottom of the default Rollup config fileto see how the IONIC_ENVenvironment variable is being used to conditionally change config values for production builds.

All Available Tasks

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

buildFull production build. Use --devflag for dev build.
bundleBundle JS modules.
cleanEmpty the wwwdirectory.
cleancssCompress the output CSS with CleanCss
copyRun the copy tasks, which by defaults copies the src/assets/and src/index.htmlfiles to www.
lintRun the linter against the source .tsfiles, using the tslint.jsonconfig file at the root.
minifyMinifies the output JS bundle and compresses the compiled CSS.
ngcRuns just the ngcportion of the production build.
sassSass compilation of used modules. Bundling must have as least ran once before Sass compilation.
transpileRuns just the tscportion of the dev build.
watchRuns watch for dev builds.

Example NPM Script:

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


  1. The Webpack devtoolsetting is driven by the ionic_source_mapvariable. It defaults to evalfor fast builds, but can provide the original source map by changing the value to source-map. There are additional values that Webpack supports, but we only support evaland source-mapsfor now.

The Stack


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

Publish a release

Execute the following steps to publish a release:

  1. Run npm run buildto generate the distdirectory
  2. Run npm run testto validate the distworks
  3. Temporarily tick the package.jsonversion
  4. Run npm run changelogto append the latest additions to the changelog
  5. Manually verify and commit the changelog changes. Often times you'll want to manually add content/instructions
  6. Revert the package.jsonversion to the original version
  7. Run npm version patchto tick the version and generate a git tag
  8. Run npm run github-releaseto create the github release entry
  9. Run npm publishto publish the package to npm





扫码加入 JavaScript 社区



欢迎加入 JavaScript 社区