license: > Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
Cordova Hooks represent special scripts which could be added by application and plugin developers or even by your own build system to customize cordova commands.
Cordova hooks allow you to perform special activities around cordova commands. For example, you may have a custom tool that checks for code formatting in your javascript file. And, you would like to run this tool before every build. In such a case, you could use a ‘before_build’ hook and instruct the cordova run time to run the custom tool to be invoked before every build.
Hooks might be related to your application activities such as before_build
, after_build
, etc. Or, they might be related to the plugins of your application. For example, hooks such as before_plugin_add
, after_plugin_add
, etc applies to plugin related activities. These hooks can be associated with all plugins within your application or be specific to only one plugin.
Cordova supports the following hook types:
Hooks could be defined in project's config.xml
using <hook>
elements, for example:
<hook type="before_build" src="scripts/appBeforeBuild.bat" /> <hook type="before_build" src="scripts/appBeforeBuild.js" /> <hook type="before_plugin_install" src="scripts/appBeforePluginInstall.js" /> <platform name="android"> <hook type="before_build" src="scripts/android/appAndroidBeforeBuild.bat" /> <hook type="before_build" src="scripts/android/appAndroidBeforeBuild.js" /> <hook type="before_plugin_install" src="scripts/android/appAndroidBeforePluginInstall.js" /> ... </platform> <platform name="windows"> <hook type="before_build" src="scripts/windows/appWinBeforeBuild.bat" /> <hook type="before_build" src="scripts/windows/appWinBeforeBuild.js" /> <hook type="before_plugin_install" src="scripts/windows/appWinBeforePluginInstall.js" /> ... </platform>
As a plugin developer you can define hook scripts using <hook>
elements in a plugin.xml
like that:
<hook type="before_plugin_install" src="scripts/beforeInstall.js" /> <hook type="after_build" src="scripts/afterBuild.js" /> <platform name="android"> <hook type="before_plugin_install" src="scripts/androidBeforeInstall.js" /> <hook type="before_build" src="scripts/androidBeforeBuild.js" /> ... </platform>
before_plugin_install
, after_plugin_install
, before_plugin_uninstall
plugin hooks will be fired exclusively for the plugin being installed/uninstalled.
Hook scripts for one given hook run serially in the order of appearance in their file with application hooks from config.xml
running before plugin hooks from plugins/.../plugin.xml
.
The internal order of execution of hooks is fixed.
If there are hooks associated with before_platform_add
, after_platform_add
, before_prepare
, after_prepare
, before_plugin_install
and after_plugin_install
(and assuming you have one plugin installed on your project), adding a new platform will execute the hooks in the following order:
before_platform_add before_prepare after_prepare before_plugin_install after_plugin_install after_platform_add
If there are hooks associated with before_prepare
, after_prepare
, before_compile
, after_compile
, before_build
and after_build
- running a build command will execute the hooks in the following order:
before_build before_prepare after_prepare before_compile after_compile after_build
If you are writing hooks using Node.js you should use the following module definition:
module.exports = function(context) { ... }
Here is an example that showcases the contents of the context
object:
{ // The type of hook being run hook: 'before_plugin_install', // Absolute path to the hook script that is currently executing scriptLocation: '/foo/scripts/appBeforePluginInstall.js', // The CLI command that lead to this hook being executed cmdLine: 'cordova plugin add plugin-withhooks', // The options associated with the current operation. // WARNING: The contents of this object vary among the different // operations and are currently not documented anywhere. opts: { projectRoot: '/foo', cordova: { platforms: ['android'], plugins: ['plugin-withhooks'], version: '0.21.7-dev' }, // Information about the plugin currently operated on. // This object will only be passed to plugin hooks scripts. plugin: { id: 'plugin-withhooks', pluginInfo: { /* ... */ }, platform: 'android', dir: '/foo/plugins/plugin-withhooks' } }, // A reference to Cordova's API cordova: { /* ... */ } }
You can also require additional Cordova modules in your script using context.requireCordovaModule
in the following way:
const cordovaCommon = context.requireCordovaModule('cordova-common');
You can make your scripts asynchronous using Promises. Here is an example that just waits for a second and then prints the amount of milliseconds spent waiting:
module.exports = context => { return new Promise(resolve => { const start = Date.now(); setTimeout(() => resolve(Date.now() - start), 1000); }).then(msWaited => { console.log(`${context.scriptLocation} waited ${msWaited} ms`); }); };
Non-javascript scripts are run via Node child_process spawn from the project's root directory and have the root directory passed as the first argument. All other options are passed to the script using environment variables:
Environment Variable Name | Description |
---|---|
CORDOVA_VERSION | The version of the Cordova-CLI. |
CORDOVA_PLATFORMS | Comma separated list of platforms that the command applies to (e.g: android, ios). |
CORDOVA_PLUGINS | Comma separated list of plugin IDs that the command applies to (e.g: cordova-plugin-file-transfer, cordova-plugin-file). |
CORDOVA_HOOK | Path to the hook that is being executed. |
CORDOVA_CMDLINE | The exact command-line arguments passed to cordova (e.g: cordova run ios --emulate). |
If a script returns a non-zero exit code, then the parent cordova command will be aborted.
Note: we highly recommend writing your hooks using Node.js so that they are cross-platform, see Javascript section above.
If you are working on Windows, and your hook scripts aren't *.bat
files, Cordova CLI will expect a shebang line as the first line of the script. This way it knows the interpreter it needs to use to launch the script. A shebang line for a Python script could look like this:
#!/usr/bin/env python
This sample demonstrates Cordova hooks usage to trace to the console output the size of generated .apk file for Android platform.
Create blank Cordova app and add the following definition to config.xml
to tell Cordova to run afterBuild.js
script after each platform build.
<hook type="after_build" src="scripts/afterBuild.js" />
Create scripts/afterBuild.js
file and add the following implementation. We use async version of fs.stat
method to demonstrate how async functions can be used in hooks.
const fs = require('fs'); const util = require('util'); const stat = util.promisify(fs.stat); module.exports = function(ctx) { // Make sure android platform is part of build if (!ctx.opts.platforms.includes('android')) return; const platformRoot = path.join(ctx.opts.projectRoot, 'platforms/android'); const apkFileLocation = path.join(platformRoot, 'build/outputs/apk/android-debug.apk'); return stat(apkFileLocation).then(stats => { console.log(`Size of ${apkFileLocation} is ${stats.size} bytes`); }); };
Parameter ctx
in example above is passed by Cordova and represents execution context such as script full path, target platform, command-line arguments, etc and also exposes additional helper functionality. See Script Interface
section above for more details.
You can now add android platform and execute build.
cordova platform add android .. cordova build .. Size of path\to\app\platforms\android\build\outputs\apk\android-debug.apk is 1821193 bytes
More good usage examples could be found in Three Hooks Your Cordova Phone Gap Project needs