Distributing Alloy Widgets via NPM

I’ve experimented with the distribution of Alloy Widgets via NPM before, but since Alloy 1.8.0 (available with Appcelerator CLI 5.2.1) we now have builtin support.

I’ll explain how I published my Loading Mask Widget to NPM and how to use it.

Publishing to NPM

Init package.json

Alloy widgets have a widget.json but NPM requires a package.json. Run npm init to generate it if you don’t already have it to manage development dependencies. Here’s some things to keep in mind as you’re filling out the fields:

  • name: Alloy expects this to be alloy-widget-<id> where <id> is what you have for the id property in the widget’s widget.json.
  • version: You’ll probably want to keep this in sync with version in widget.json.
  • description: Likewise.. I feel a Grunt / Gulp script coming!
  • entry point: Doesn’t really apply since the un-compiled widget is of no use in Node.js. Perhaps set widget.json so it would export the widget’s meta data?
  • keywords: Copy tags from your widget.json, but also add appcelerator,titanium,alloy,widget. We require these keywords to ensure widgets are easily discoverable on NPM.
  • author and license: Again borrow from widget.json but be aware that license should be a SPDX license identifier for NPM.

Now all we have to do is publish:

$ npm publish
+ alloy-widget-nl.fokkezb.loading@1.8.4

And there we are:


Keep in sync

Remember to keep widget.json and package.json in sync, in particular version-wise. Since a both files share a lot of fields you’ll probably want to script this.

Depending and Installing from NPM

Now how do we use this in an app?

Add to config.json

Where the gitTio CLI does this automatically for you, npm install --save of course is not aware of Alloy’s config.json file. So you’ll have to manually add the dependency. Use the widget ID here and not the NPM package name:

"dependencies": {
"nl.fokkezb.loading": "*"
Install local

Normally you’d install the widget local to the project. In the root of the project (where tiapp.xml is) run:

$ npm install --save alloy-widget-nl.fokkezb.loading

You will probably want to add --save to save the dependency to the project’s package.json. If you don’t already have this file to manage your development dependencies (e.g. Grunt / Gulp scripts) create this file first using npm init. Using --save will not do this for you.


You can also install the widget as a global NPM package. This allows you to use the same widget in multiple projects:

$ sudo npm install -g alloy-widget-nl.fokkezb.loading

How does it work?

Alloy will now automagically find the widget when it compiles. You’ll notice app/widgets will not have the widget at all. Every time Alloy compiles it uses resolve to resolve any widgets that have not been found in the widgets folder. They will be compiled directly to Resources.


NPMs new scoped packages are known not to work with Alloy.


The new Marketplace which at the moment only supports Arrow Connectors will also support Titanium modules, Alloy widgets and other components in the future. This will allow you to make money on your widgets or restrict the usage to your organisation only.

Code Strong! ?

Previous articleDevoxxFr 2016 – Part 3
Next articleGartner AADI Summit in London
Developer Evangelist


Please enter your comment!
Please enter your name here