Ionic Framework 4 is almost here. Preview the beta docs and try it out now! Try Ionic 4 Beta

Ionic apps utilize TypeScript and Sass code. This code needs to be converted into web browser friendly code. A build process is required to achieve this. @ionic/app-scripts are a set of configurable scripts provided to make it easy to create a simple or a highly customized build process.

How does it work?

Ionic app’s are developed typically using the ionic serve and ionic cordova run commands. Both of these commands need to compile the application’s code and combine it into one bundled file.

When ionic serve or ionic cordova run are invoked, it ultimately calls an NPM script. These npm scripts call the @ionic/app-scripts library to execute the build process.

Why App Scripts?

Most application’s share a similar build process. Rather than have each user create their own build process from scratch for their app, we thought that time would be better spent building out their Ionic app and leaving the details to us. This is our interpretation of what most users need from a build process.

What About Gulp?

Historically Ionic apps have used gulp as tool to facilitate the build process. Over the years, gulp has seen less and less development, and has started to accumulate deprecation warnings. By taking advantage of standard and dependency free NPM scripts, we are reducing dependencies and simplifying the development experience.

Note: Developers are free to still use gulp if they choose to do so. We think NPM scripts are a better approach, but there is nothing in place restricting the use of gulp if that is the preferred method.

What Scripts are Provided?

@ionic/app-scripts provides the following scripts:

Providing Custom Build Configuration

The default configured provided by @ionic/app-scripts covers many of the scenarios required by developers. However, if a developer wants to customize and configure the way the build process is run, they can do so.

The easiest way to configure @ionic/app-scripts is to take advantage of the config option in the package.json file.

To get started, add a config entry to the package.json file. From there, developers can provide their own configuration file for things like minification (closure compiler, uglify2), and bundling (webpack).

See an example of specifying a custom configuration file below:

  "config": {
    "ionic_webpack": "./config/webpack.config.js",
    "ionic_cleancss": "./config/cleancss.config.js",

In the above example, custom configurations for webpack and cleancss are provided by a path to a config file.

The following config values are used to map to a task’s config file.

Config File NPM Config Property
CleanCss ionic_cleancss
Closure Compiler ionic_closure
Copy ionic_copy
NGC ionic_ngc
Webpack ionic_webpack
Sass ionic_sass
TSLint ionic_tslint
UglifyJS ionic_uglifyjs

The default configurations are great examples to learn about customization options.

Note: Command line flags can also be used to provide custom configuration.

Custom Project Structure

In most cases, the default project structure provided by Ionic works great! However, if a developer chooses to modify the structure to suit their use case, they are welcome to do so.

Using the same concepts outlined above for providing configuration using the package.json config option, developers can specify their own custom project structure.

Config Values NPM Config Property Defaults
root directory ionic_root_dir process.cwd()
tmp directory ionic_tmp_dir .tmp
src directory ionic_src_dir src
www directory ionic_www_dir www
build directory ionic_build_dir build

Ionic Environment Variable

An environment variable, IONIC_ENV is available in the build process to help determining whether a build is a development build, or a production build. The environment variable can be accessed like this:

if (process.env.IONIC_ENV === 'prod') {
  console.log('we got a production buildp');
} else {
  console.log('we got a development build');

Task Details


Ionic uses a tool called webpack to combine multiple javascript files into one combined file. This process is often called bundling code for deployment.