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:

• build : build calls a set of @ionic/app-scripts to compile the TypeScript source, compile sass, create a bundle javascript file, etc.

• bundle : bundle uses webpack to produce a single, high performance javascript file from the many smaller javascript files.

• clean : clean deletes any of the files generated by the build process. Basically, it deletes the www directory.

• cleancss : cleancss uses CleanCSS to minify css to it’s smallest, fastest form.

• closure : closure uses Google’s Closure Compiler to minify javascript to it’s smallest, fastest form.

• copy : copy copies files where they need to go to end up in the built www directory.

• lint : lint runs TSLint against the TypeScript source code. Requires a tslint.json file at the project root.

• minify : minify calls the minification tasks for javascript (uglify, or closure if available) and css (cleancss).

• ngc : ngc calls the Angular Ahead-of-time compiler to create extremely fast apps.

• sass : sass walks the application’s directory tree to find scss files and assemble them into one css file.

• template : template is used to convert Angular templates into inline-templates for faster loading and faster applications during the development process.

• transpile : transpile converts TypeScript code into javascript code.

• tsc : tsc calls the TypeScript compiler.

• uglifyjs : uglifyjs is used to minify javascript to it’s smallest and fastest form.

• watch : watch creates a smaller, faster build process to be used during application development.

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.

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.

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

Bundle

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