How to restrict an app to specific Titanium & Alloy versions

You set the Titanium SDK version to compile your app with in tiapp.xml. If it’s an Alloy app you can set the Alloy version to compile with. If you use the stand-alone Titanium CLI then it will use whatever version of the stand-alone Alloy CLI you have installed. If you use the unified Appcelerator CLI it will use the Alloy version that is embedded in the Appcelerator CLI Core Package that you have selected with appc use. Read Understanding the Unified Appcelerator CLI for more background on that.

Why would want to require specific versions?

Sometimes you will want to restrict your app to certain versions of the Titanium SDK and Alloy MVC. One example are our release sample apps. They are meant to be compiled using a specific Titanium minor version and generally require the latest Alloy version at the time of release.

When you import a sample app it will set the <sdk-version> in tiapp.xml to the latest installed SDK if the one set cannot be found. And like we saw the Alloy version depends on the environment as well. So it might well be that the sample will fail to compile or run, leaving the developer in the dark on the reasons why.

How to do it?

So, after updating the Titanium 5.2 Sample App to take advantage of some new fixes and features Titanium 5.2.2.GA and Alloy 1.8.5, I added two simple scripts to make sure the app only compiles on those or later versions and provides helpful feedback when those requirements are not met.

Limit to a range of Titanium SDK versions

In plugins/ti.version/1.0/hooks/version.js you’ll find a new 8-line Titanium CLI Plugin.

Drop this plugin into a project and register it in the <plugins> section of your tiapp.xml. Then add a <property> element to set the semver range your app supports:

    <plugin version="1.0">ti.alloy</plugin>
    <plugin version="1.0">ti.version</plugin>
  <property name="ti.version.range" type="string">&gt;=5.2.2 &lt;5.3</property>

NOTE: As you can we need to encode any special XML characters like < and >.

When someone compiles your app with an unsupported version it will fail with something like:

[INFO]  Found Titanium plugin id=ti.version version=1.0
[ERROR] This app requires Titanium SDK >=5.2.2 <5.3 instead of 5.1.2.GA (5.1.2.v20151216190036)

Require a minimum Alloy version

For Alloy I’ve added a hook to app/alloy.jmk – the so-called Build Configuration File. This hook receives the minimum version we set in app/config.json and checks this against the Alloy version used to compile. If an older Alloy version is used it will fail with a message like:

[INFO]  Found Alloy app in /Users/fokkezb/dev/samples/appc-sample-ti520/app
[INFO]  Executing Alloy compile: /usr/local/bin/node /Users/fokkezb/.appcelerator/install/5.2.2/package/node_modules/alloy/bin/alloy compile /Users/fokkezb/dev/samples/appc-sample-ti520/app --config platform=ios,version=0,simtype=none,devicefamily=universal,deploytype=development,target=simulator
[INFO]   [config.json] regenerating CFG.js from config.json...
[ERROR] This app requires Alloy 1.8.5 or later instead of 1.7.35
[ERROR] Alloy compiler failed

NOTE: We don’t have access to the node-appc package in the context where alloy.jmk is executed. I didn’t want to introduce a dependency which is why I use a simple helper method to convert a string version to an integer. This is why it only supports checking against a minimum version, not a range.

Even though you might not need this 1:1 I hope to have learned you a thing or two on using a Titanium CLI Plugin or Build Configuration File.

Code Strong! ?

Previous articleAxway APAC Partner Summit in Singapore
Next articleCustom Error Pages for Arrow Web
Developer Evangelist


  1. I dont see the point of this. Why cant we assign the exact Alloy version in the tiapp.xml just like the Ti SDK version? If you want to have a stable build you are better off not to allow a certain range, but only a certain version for which you know it works.
    It would help me out a lot for instance with the latest Alloy build (1.8.5?), it caused quite some bugs in my app and I’m having trouble downgrading using `appc`. The way how `appc` comes with a certain Alloy version is very confusing too. The build process doesnt even show which Alloy version is used during compilation.
    Why cant we just define the exact modules we want to use? Same for Backbone/Underscore. I understand the restriction to allow a stable version to exist, but it would be a lot better to ship Alloy with a recommended setup which the end-user is then able to edit

    • This has to due with how Alloy is currently architected as a AppC/Titanium CLI plugin and that you only have one Alloy version installed when you are using the OSS Titanium CLI and only one Alloy version available when you are using the AppC CLI. We are currently refactoring the build process and as part of this Alloy will merge with the Titanium SDK. Once that is done, the Alloy (then Titanium MVC) version will be the SDK you select.
      You can see what Alloy version an AppC CLI version comes with with appc alloy -v or by checking the AppC CLI Release Notes.
      Alloy is built on Backbone and Underscore so to make sure Alloy works we ship versions we know it works with. But, you can replace them very easily. Simply create an app/lib/alloy folder and in there drop the underscore.js and/or backbone.js files you’d like to use.

      • Alright this seems like a good change. I wouldve loved to see this happen earlier since it seems now the `npm appcelerator` package is defeating the purpose of something like a package.json file for managing your packages.
        I think the ultimate goal is to reach a setup where the developer has the option to choose which modules+versions to use in the app (including the dependencies of alloy) to allow more control over the end-result.
        I will look into the app/lib/alloy folder, I think this might be a solution to some other restrictions im currently trying to circumvent. Thanks!

        • For Titanium modules you can specify the exact version tiapp.xml. Except for modules available via the gitTio CLI this will still require you to install these versions of course. We’re working on a replacement for the Marketplace that includes distribution via CLI/Studio.
          We’re also consolidating components like Alloy and the Titanium SDK that depend to heavily on each other to use different versions of into less components. TL;DR Alloy will merge with the Titanium SDK.
          Finally, we’re working on better CommonJS and even NPM package support for using libraries in the apps themselves so that indeed you would be able to depend on certain versions of underscore, moment.js via a package manifest.


Please enter your comment!
Please enter your name here