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 

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.

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

 "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 

In many cases, the defaults which Ionic provides covers 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

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_bundler": "rollup", "ionic_source_map": "source-map", "ionic_cleancss": "./config/cleancss.config.js" }, 

Remember how we're actually running ionic-app-scripts from the scripts property of 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 --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 run commands too, such as:

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

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.

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 task is prod, and the watch and serve tasks are dev. Additionally, using the --dev command line flag will force the build to use dev.

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

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

Example NPM Script:

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

Injecting dynamic data into the build is accomplished via hooks. Hooks are functions for performing actions like string replacements. Hooks must return a Promise or the build process will not work correctly.

For now, two hooks exist: the pre-bundle and post-bundle hooks.

To get started with a hook, add an entry to the package.json config section

... "config": { "ionic_pre_bundle_hook": "./path/to/some/file.js" } ... 

The hook itself has a very simple api

module.exports = function(context, isUpdate, changedFiles, configFile) { return new Promise(function(resolve, reject) { // do something interesting and resolve the promise }); } 

context is the app-scripts BuildContext object. It contains all of the paths and information about the application.

isUpdate is a boolean informing the user whether it is the initial full build (false), or a subsequent, incremental build (true).

changedFiles is a list of File objects for any files that changed as part of an update. changedFiles is null for full builds, and a populated list when isUpdate is true.

configFile is the config file corresponding to the hook's utility. For example, it could be the rollup config file, or the webpack config file depending on what the value of ionic_bundler is set to.

Here is an example of doing string replacement. We're injecting the git commit hash into our application using the ionic_pre_bundle_hook.

var execSync = require('child_process').execSync; // the pre-bundle hook happens after the TypeScript code has been transpiled, but before it has been bundled together. // this means that if you want to modify code, you're going to want to do so on the in-memory javascript // files instead of the typescript files module.exports = function(context, isUpdate, changedFiles, configFile) { return new Promise(function(resolve, reject) { // get the git hash var gitHash = execSync('git rev-parse --short HEAD').toString().trim(); // get all files, and loop over them const files = context.fileCache.getAll(); // find the transpiled javascript file we're looking for files.forEach(function(file) { if (file.path.indexOf('about.js') >= 0) { file.content = file.content.replace('$GIT_COMMIT_HASH', gitHash); } }); resolve(); }); } 

1. The Webpack devtool setting is driven by the ionic_source_map variable. It defaults to eval for 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 eval and source-maps for now.

• Ionic Framework
• TypeScript Compiler
• Angular Compiler (NGC)
• Rollup Module Bundler
• Ionic Component Sass
• Node Sass
• Autoprefixer
• UglifyJS
• CleanCss
• TSLint

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

Execute the following steps to publish a release:

1. Run npm run build to generate the dist directory
2. Run npm run test to validate the dist works
3. Temporarily tick the package.json version
4. Run npm run changelog to 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.json version to the original version
7. Run npm version patch to tick the version and generate a git tag
8. Run npm run github-release to create the github release entry
9. Run npm publish to publish the package to npm