Hooks

Hooks are special scripts which you can add to the build process of your app. They are available to Pro and Enterprise Plans.

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 files which you would like to run before every build. In such a case, you could use a before_build hook and add a line to config.xml to run it 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 apply to plugin related activities. These hooks can be associated with all plugins within your application or be specific to only one plugin.

For more information, see Cordova’s docs on Hooks.

Calling a hook

You specify which hooks to call in your config.xml file. Here’s a sample:

<hook type="after_build" src="scripts/afterBuild.js" />

There are 16 possible values for type, listed here.

Your scripts should be in a folder called scripts in the root of your project. (You can put it somewhere else - just be consistent)

Hook Scripts

Hook scripts can be JavaScript or batch (.bat): JavaScript is recommended for cross platform compatibility.

Here’s a sample script to output the size of the generated apk from an Android build.

const fs = require('fs');
const path = require('path');
const util = require('util');
const stat = util.promisify(fs.stat);

module.exports = function(ctx) {
    // next line is optional, but will make debugging easier.
    console.log(`Hook called: ${ctx.hook} ${ctx.scriptLocation}`);

    try {
    // 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, 'app/build/outputs/apk/debug/app-debug.apk');

      return stat(apkFileLocation).then(stats => {
        console.log(`Size of ${apkFileLocation} is ${stats.size} bytes`);
      });
    } catch(e) {
      throw `Hook error: ${e}`;
    }
};

Notes:

  • You can use node modules - the scripts run in a node context.
  • When a script gets called, the context object is passed to the script. See ctx in the script above.
  • The context object contains information about the script.
  • You can examine what is in ctx by adding a statement like this to your script:
console.log(JSON.stringify(ctx));
  • Check your code carefully. If there is a syntax error, a message will be output to the log, but the build will continue as if the script was not called.
  • It’s a good idea to enclose your code in a try - catch structure, so errors will interrupt the build and be reported in the log.
  • If VoltBuilder cannot find the script, the build will continue as if the script was not called.

Other Considerations

Hooks are not supported on Windows.