Configuration

Configuration values are stored in JSON files. The Ionic CLI maintains a global configuration file, usually located at ~/.ionic/config.json, and project configuration files, usually at the project's root directory as ionic.config.json.

The CLI provides commands for setting and printing config values from project config files and the global CLI config file. See ionic config --help or see the documentation for usage of ionic config get and ionic config set.

Each Ionic project has a project configuration file, usually at the project's root directory. The following is an annotated ionic.config.json file.

{
// The human-readable name of the app.
"name":"My App",
// The project type of the app. The CLI uses this value to determine which
// commands and command options are available, what to output for help
// documentation, and what to use for web asset builds and the dev server.
"type":"angular",
// The App ID for Ionic Appflow.
"id":"abc123",
// Configuration object for integrations such as Cordova and Capacitor.
"integrations":{"cordova":{
...
}},
// Hook configuration--see the Hooks section below for details.
"hooks":{
...
}}

The CLI can run scripts during certain events, such as before and after builds. To hook into the CLI, the following npm scripts can be used in package.json:

ionic:serve:before: executed before the dev server starts

ionic:serve:after: executed after the dev server is terminated

ionic:build:before: executed before a web asset build begins

ionic:build:after: executed after a web asset build finishes

Hooks can also be defined in ionic.config.json. Define a hooks object within the project, where each key is the name of the hook (without the ionic: prefix), and the value is a path to a JavaScript file or an array of paths.

In the following example, the file is imported and run during the ionic:build:before hook.

"hooks":{"build:before":"./scripts/build-before.js"},

JavaScript hook files should export a single function, which is passed a single argument (ctx) whenever the hook executes.

The argument is the context given to the hook file, which differs from hook to hook and with different invocations.

In a multi-app project, apps share a single ionic.config.json file at the root of the repository instead of each app having their own. The multi-app config file contains the configuration for each app by nesting configuration objects in a projects object. A default app can be specified using defaultProject.

Below is an example file, which corresponds to the file structure above.

When a multi-app project is detected, the Ionic CLI will operate under the context of an app configured in the root ionic.config.json. Project selection criteria is as follows:

If the global CLI option --project is specified, the project is looked up by key in the projects object. For example, --project=myApp will select the myApp project.

If the CLI detects it is being run within a project path, configured with the root key, it will select the matched project. For example, using the CLI within the apps/myOtherApp/src directory will select the myOtherApp project.

If a defaultProject is specified in ionic.config.json, it will select the specified project when the above criteria is not met.

Normally, the CLI runs a hard-coded set of commands based on the project type. For example, the standard web asset build for Angular projects is ng run app:build. The web asset build can be overridden and ionic build can continue to be used by utilizing the ionic:buildnpm script. Similarly, the dev server can be overridden by using the ionic:serve npm script.

Pay close attention to the flags supplied to the script by the Ionic CLI. Irregularities may occur if options are not respected, especially for livereload on devices.

Command options can be expressed with environment variables. They are normally set with --opt=value syntax. The naming of these environment variables follows a pattern: start with IONIC_CMDOPTS_, add the command name (replacing any spaces with underscores), add the option name (replacing any hyphens with underscores), and then uppercase everything. Boolean flags (command-line options that don't take a value) can be set to 1 or 0. Strip the --no- prefix in boolean flags, if it exists (--no-open in ionic serve can be expressed with IONIC_CMDOPTS_SERVE_OPEN=0, for example).

For example, the command options in ionic cordova run ios -lc --livereload-port=1234 --address=localhost can also be expressed with this series of environment variables: