Alloy MVC Framework for Titanium SDK

3.0.0 · active · verified Sun Apr 19

Alloy is an MVC (Model-View-Controller) application framework specifically designed for building cross-platform native mobile applications with the TiDev Titanium SDK. It provides a structured approach to developing Titanium apps by separating concerns into XML-based views, JavaScript controllers, and data models/collections (leveraging Backbone.js internally). The current stable version is 3.0.0, released in 2026. While not on a strict calendar-based release cadence, it receives active maintenance with several minor and major releases per year, as seen with versions 2.0.0, 2.1.0, and 3.0.0 released in 2024-2026. Its key differentiator is its tight integration with the Titanium SDK, offering a declarative UI (XML) and convention-over-configuration for mobile app development on iOS and Android platforms.

Common errors

```
Error: EACCES: permission denied, open '/usr/local/lib/node_modules/jake/...' (or similar permission errors on CLI)
```
cause Insufficient operating system permissions for Node.js to install global packages or execute scripts, particularly on macOS/Linux without elevated privileges.

fix Use `sudo npm install -g alloy` and `sudo npm install -g jake` for global installations on macOS/Linux. For script execution, use `sudo jake app:run ...` if permission errors persist. On Windows, ensure you are not running from restricted user folders like `C:\Users\yourName`.
```
Unable to find the alloy cli. Ensure it is installed and in your PATH.
```
cause The 'alloy' command-line interface tool is not globally installed or its executable path is not correctly configured in the system's PATH environment variable.

fix Install Alloy globally using npm: `npm install -g alloy`. If already installed, verify your system's PATH environment variable includes the npm global bin directory.
```
TypeError: Invalid value passed to event listener for 'widgetname'. Expected String, got Object.
```
cause Providing incorrect data types or structures to Alloy's event listeners or other API methods. Alloy is strict about expected input types.

fix Refer to the Titanium SDK and Alloy framework documentation for the specific API method or event listener you are using. Verify the expected argument types and formats and ensure your code provides them correctly.

Warnings

breaking Major version updates (e.g., v2.0.0 to v3.0.0) often involve significant internal changes like 'remove old code' and 'fix sdk version'. These changes imply potential incompatibilities with older Titanium SDK versions or deprecated patterns. Developers should consult release notes for specific migration guides.
Fix: Review the specific changelogs and update application code and your Titanium SDK version to match the requirements of the new Alloy version.
deprecated The package requires Node.js version 20.18.1 or higher as per its `engines` specification. Using older Node.js versions will lead to installation or runtime errors with the CLI tool. This is a significant bump compared to many other packages.
Fix: Upgrade Node.js to version 20.18.1 or newer. Utilize Node Version Manager (NVM) or a similar tool for seamless management of multiple Node.js versions.
breaking Manual updates for internal dependencies like `moment.js`, `Backbone.js`, and `Underscore.js` often involve manually copying files into specific `Alloy/builtins` folders. Incorrect placement or outdated files can lead to runtime errors or unexpected behavior.
Fix: Follow the documentation precisely for manual updates, ensuring files are placed in the correct `Alloy/builtins` subdirectories. Where possible, rely on `npm update` for managed dependencies, or consult the changelog for specific update instructions.
gotcha When running `jake` commands (often used for development and testing) on Windows, executing them from user-specific folders (e.g., `C:\Users\yourName\alloy`) can cause non-obvious permission errors and child process failures.
Fix: Clone the Alloy repository to a root-level directory, such as `C:\alloy`, and execute `jake` commands from there to mitigate permission-related issues.
gotcha On Windows, if running `jake` tests for an Alloy project that has been imported into Titanium Studio, ensure Titanium Studio is completely closed. Windows creates file locks on project files that are necessary for the testing process, leading to erroneous test failures.
Fix: Always close Titanium Studio before initiating `jake` test runs on Windows to release file locks and ensure accurate test execution.
breaking Versions prior to 1.17.3 (released Jan 2022) were susceptible to a potential denial-of-service vulnerability due to an un-pinned dependency on the `colors.js` package, which had a malicious update.
Fix: Immediately update Alloy to version 1.17.3 or newer to patch this dependency and ensure supply chain security. If unable to update Alloy, consider auditing `colors.js` version directly.
breaking Versions prior to 1.17.2 (released Jan 2022) might be exposed to vulnerabilities through an outdated `xmldom` dependency. Version 1.17.2 bumped `xmldom` to 0.8.0, addressing potential security concerns.
Fix: Update Alloy to version 1.17.2 or newer to ensure the `xmldom` dependency is updated to a more secure version.

Install

npm install alloy npm
yarn add alloy yarn
pnpm add alloy pnpm

Imports

Alloy (global object)
wrong:
```
import { Alloy } from 'alloy'
```
correct:
```
// The 'Alloy' object is globally available within the Titanium application runtime.
```
Alloy is primarily a build-time framework and CLI tool. Its core runtime features are exposed via a global 'Alloy' object within the compiled Titanium application, not by direct ES module or CommonJS import of the 'alloy' npm package.
Alloy.createController()
wrong:
```
import { createController } from 'alloy'; createController('my_controller');
```
correct:
```
const myController = Alloy.createController('my_controller');
```
Used within Titanium app controllers to instantiate other controllers or access specific views. This function is part of the global 'Alloy' object provided at runtime by the framework.
Alloy.Models.instance()
wrong:
```
import { Models } from 'alloy'; Models.instance('user');
```
correct:
```
const userModel = Alloy.Models.instance('user');
```
Provides access to singleton model instances defined in the Alloy project's models folder. Part of the global 'Alloy' object provided at runtime.

Quickstart

This quickstart demonstrates how to initialize a new Titanium mobile application, convert it to an Alloy project using the `alloy new` command with a sample template, and then build it for a target platform.

/* 
  This quickstart demonstrates how to set up a new Titanium Alloy project 
  using the Alloy CLI tool and a sample application template. 
  This is executed from your system's terminal, not a JavaScript file.
*/

# 1. Install Titanium CLI and Alloy globally (if not already installed)
npm install -g titanium alloy

# 2. Create a new Titanium Classic project as a base
titanium create \
  --name MyAlloyApp \
  --id com.example.myalloyapp \
  --platform ios,android \
  --sdk latest \
  --type classic

# 3. Navigate into the newly created project directory
cd MyAlloyApp

# 4. Convert the Classic project to an Alloy project using a sample template
alloy new . --testapp basics/simple

# 5. Build and run the application (e.g., for iOS simulator)
titanium build --platform ios --target simulator --device-id iPhone

/* 
  The 'alloy new . --testapp basics/simple' command will populate your project
  with the files from the 'basics/simple' Alloy sample, providing a runnable 
  Alloy application structure ready for development.
*/

view raw JSON →