Configuration
#
FilesConfiguration 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
.
#
Project Configuration FileEach Ionic project has a project configuration file, usually at the project's root directory. The following is an annotated ionic.config.json
file.
#
Environment VariablesThe CLI will look for the following environment variables:
IONIC_CONFIG_DIRECTORY
: The directory of the global CLI config. Defaults to~/.ionic
.IONIC_HTTP_PROXY
: Set a URL for proxying all CLI requests through. See Using a Proxy.IONIC_TOKEN
: Automatically authenticates with Appflow.
#
FlagsCLI flags are global options that alter the behavior of a CLI command.
--help
: Instead of running the command, view its help page.--verbose
: Show all log messages for debugging purposes.--quiet
: Only showWARN
andERROR
log messages.--no-interactive
: Turn off interactive prompts and fancy outputs. If CI or a non-TTY terminal is detected, the CLI is automatically non-interactive.--confirm
: Turn on auto-confirmation of confirmation prompts. Careful: the CLI prompts before doing something potentially harmful. Auto-confirming may have unintended results.
#
HooksThe 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 startsionic:serve:after
: executed after the dev server is terminatedionic:build:before
: executed before a web asset build beginsionic:build:after
: executed after a web asset build finishesionic:capacitor:run:before
: executed duringionic capacitor run
before capacitor open is executedionic:capacitor:build:before
: executed duringionic capacitor build
before capacitor open is executedionic:capacitor:sync:after
: executed duringionic capacitor sync
after a sync
When using a shell script for any of the hooks, hook context is defined in environment variables prefixed with IONIC_CLI_HOOK_CTX_
.
The following example shows the environment variables that are set for the ionic:capacitor:build
hook.
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.
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.
./scripts/build-before.js
:
#
Available in CLI 6.2.0+ Multi-app ProjectsThe Ionic CLI supports a multi-app configuration setup, which involves multiple Ionic apps and shared code within a single repository, or monorepo.
These docs give an overview of the multi-app feature of the Ionic CLI, but don't really go into details for each framework.
If you're using Angular, please see this article for examples.
#
Setup StepsCreate a directory and initialize a monorepo (see Project Structure for full details).
Initialize the monorepo as an Ionic multi-app project. This will create a multi-app
ionic.config.json
file. See Config File for full details.Use
ionic start
to create Ionic apps orionic init
to initialize existing apps (see Adding an App for full details).
#
Project StructureIn a multi-app project, project structure is flexible. The only requirement is a multi-app ionic.config.json
file at the root of the repository.
Below is an example setup, where apps in the apps/
directory are separated from the shared code in the lib/
directory. Notice the root ionic.config.json
file and the monorepo's package.json
file.
#
Config FileIn 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 theprojects
object. For example,--project=myApp
will select themyApp
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 theapps/myOtherApp/src
directory will select themyOtherApp
project. - If a
defaultProject
is specified inionic.config.json
, it will select the specified project when the above criteria is not met.
#
Adding an AppApps can be registered in a multi-app project either by using ionic start
to create new apps or ionic init
to initialize existing apps.
ionic start
#
Using If a multi-app project is detected during ionic start
, the CLI will add the app configuration to the root ionic.config.json
file instead of creating a project-specific one.
Dependency installation can be skipped using --no-deps
if dependencies are hoisted to the root of the monorepo.
ionic init
#
Using If an app was created in a way other than ionic start
, for example by using a prebuilt template, use ionic init
to register the existing app with the multi-app project.
Make sure the app doesn't have an existing
ionic.config.json
.
#
Advanced Configuration#
Overriding the BuildNormally, 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:build
npm 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 OptionsCommand 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 --host=0.0.0.0
can also be expressed with this series of environment variables:
If these variables are set in the environment, ionic cordova build ios
will use new defaults for its options.
#
TelemetryThe CLI sends usage data to Ionic to create a better experience. To disable this functionality, run ionic config set -g telemetry false
.