{"id":10494,"library":"alloy","title":"Alloy MVC Framework for Titanium SDK","description":"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.","status":"active","version":"3.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/tidev/alloy","tags":["javascript","titanium","alloy","mobile","ios","iphone","android","html5","appc-client"],"install":[{"cmd":"npm install alloy","lang":"bash","label":"npm"},{"cmd":"yarn add alloy","lang":"bash","label":"yarn"},{"cmd":"pnpm add alloy","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Alloy builds applications for the Titanium SDK, requiring the Titanium CLI for project creation and compilation.","package":"titanium","optional":false},{"reason":"Used for running sample applications and local testing when developing Alloy itself or its samples.","package":"jake","optional":true}],"imports":[{"note":"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.","wrong":"import { Alloy } from 'alloy'","symbol":"Alloy (global object)","correct":"// The 'Alloy' object is globally available within the Titanium application runtime."},{"note":"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.","wrong":"import { createController } from 'alloy'; createController('my_controller');","symbol":"Alloy.createController()","correct":"const myController = Alloy.createController('my_controller');"},{"note":"Provides access to singleton model instances defined in the Alloy project's models folder. Part of the global 'Alloy' object provided at runtime.","wrong":"import { Models } from 'alloy'; Models.instance('user');","symbol":"Alloy.Models.instance()","correct":"const userModel = Alloy.Models.instance('user');"}],"quickstart":{"code":"/* \n  This quickstart demonstrates how to set up a new Titanium Alloy project \n  using the Alloy CLI tool and a sample application template. \n  This is executed from your system's terminal, not a JavaScript file.\n*/\n\n# 1. Install Titanium CLI and Alloy globally (if not already installed)\nnpm install -g titanium alloy\n\n# 2. Create a new Titanium Classic project as a base\ntitanium create \\\n  --name MyAlloyApp \\\n  --id com.example.myalloyapp \\\n  --platform ios,android \\\n  --sdk latest \\\n  --type classic\n\n# 3. Navigate into the newly created project directory\ncd MyAlloyApp\n\n# 4. Convert the Classic project to an Alloy project using a sample template\nalloy new . --testapp basics/simple\n\n# 5. Build and run the application (e.g., for iOS simulator)\ntitanium build --platform ios --target simulator --device-id iPhone\n\n/* \n  The 'alloy new . --testapp basics/simple' command will populate your project\n  with the files from the 'basics/simple' Alloy sample, providing a runnable \n  Alloy application structure ready for development.\n*/","lang":"bash","description":"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."},"warnings":[{"fix":"Review the specific changelogs and update application code and your Titanium SDK version to match the requirements of the new Alloy version.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"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.","severity":"deprecated","affected_versions":">=3.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":"all"},{"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.","message":"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.","severity":"gotcha","affected_versions":"all"},{"fix":"Always close Titanium Studio before initiating `jake` test runs on Windows to release file locks and ensure accurate test execution.","message":"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.","severity":"gotcha","affected_versions":"all"},{"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.","message":"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.","severity":"breaking","affected_versions":"<1.17.3"},{"fix":"Update Alloy to version 1.17.2 or newer to ensure the `xmldom` dependency is updated to a more secure version.","message":"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.","severity":"breaking","affected_versions":"<1.17.2"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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`.","cause":"Insufficient operating system permissions for Node.js to install global packages or execute scripts, particularly on macOS/Linux without elevated privileges.","error":"Error: EACCES: permission denied, open '/usr/local/lib/node_modules/jake/...' (or similar permission errors on CLI)"},{"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.","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.","error":"Unable to find the alloy cli. Ensure it is installed and in your PATH."},{"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.","cause":"Providing incorrect data types or structures to Alloy's event listeners or other API methods. Alloy is strict about expected input types.","error":"TypeError: Invalid value passed to event listener for 'widgetname'. Expected String, got Object."}],"ecosystem":"npm"}