README
Ionic App Scripts
Helper scripts to get Ionic apps up and running quickly (minus the config overload).
Config Defaults
Out of the box, Ionic starters have been preconfigured with great defaults for building fast apps, including:
- Transpiling source code to ES5 JavaScript
- Ahead of Time (AoT) template compiling
- Just in Time (JiT) template compiling
- 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 towww
- 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.
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 within the project's package.json
file. For example, this is the default setup for npm scripts within each starters:
"scripts": {
"build": "ionic-app-scripts build",
"watch": "ionic-app-scripts watch"
},
To run the build
script found in the package.json
scripts
property, execute:
npm run build
Custom Config Files
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 configurations.
NPM Config
Within the package.json
file, NPM also provides a handy config property. Below is an example of setting a custom config file using the config
property in a project's package.json
.
"config": {
"ionic_rollup": "./config/rollup.config.js",
"ionic_cleancss": "./config/cleancss.config.js"
},
Command-line Flags
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
Overriding Config Files
Config File | NPM Config Property | Cmd-line Flag |
---|---|---|
CleanCss | ionic_cleancss |
--cleancss or -e |
Copy | ionic_copy |
--copy or -y |
Generator | ionic_generator |
--generator or -g |
NGC | ionic_ngc |
--ngc or -n |
Rollup | ionic_rollup |
--rollup or -r |
Sass | ionic_sass |
--sass or -s |
TSLint | ionic_tslint |
--tslint or -l |
UglifyJS | ionic_uglifyjs |
--uglifyjs or -u |
Overriding Config Values
Config Values | NPM Config Property | Cmd-line Flag | Defaults |
---|---|---|---|
root directory | ionic_root_dir |
--rootDir |
process.cwd() |
tmp directory | ionic_tmp_dir |
--tmpDir |
.tmp |
src directory | ionic_src_dir |
--srcDir |
src |
www directory | ionic_www_dir |
--wwwDir |
www |
build directory | ionic_build_dir |
--buildDir |
build |
Ionic Environment Variable
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
task is dev
. Note that ionic serve
uses the watch
task. 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.
All Available Tasks
These tasks are available within ionic-app-scripts
and can be added to NPM scripts or any Node command.
Task | Description |
---|---|
build |
Full production build. Use --dev flag for dev build. |
bundle |
Bundle JS modules. |
clean |
Empty the www directory. |
cleancss |
Compress the output CSS with CleanCss |
copy |
Run the copy tasks, which by defaults copies the src/assets/ and src/index.html files to www . |
lint |
Run the linter against the source .ts files, using the tslint.json config file at the root. |
minify |
Minifies the output JS bundle and compresses the compiled CSS. |
ngc |
Runs just the ngc portion of the production build. |
sass |
Sass compilation of used modules. Bundling must have as least ran once before Sass compilation. |
tsc |
Runs just the tsc portion of the dev build. |
watch |
Runs watch for dev builds. |
Example NPM Script:
"scripts": {
"minify": "ionic-app-scripts minify"
},